# Elastic Path Documentation

> API, Commerce Manager, Guides and Documentation 🚀

This file contains all documentation content in a single document following the llmstxt.org standard.

## Account Authentication Settings

You can use the Account Authentication Settings endpoint to retrieve or modify how settings controlling account and account member authentication.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Account Management Authentication

Commerce provides authentication tokens for an `Account` and an `Account Member`.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Account Management Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/accounts/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Account Management Introduction"}
>
</Heading>

An Account represents the entity that participates in a Commerce transaction. Accounts can have Carts, Orders,
Subscriptions, and Addresses.

Each account can have multiple account members, which represent users and can transact on behalf of the account.

In a typical B2C scenario, an account usually has a single account member. However, this functionality can also be
used to support use cases such as family accounts, allowing multiple family members to transact on behalf of their
shared account. In a B2B scenario, an account will have multiple members from a business unit, all of whom can
transact on behalf of their organization.

Accounts can be grouped together using Account Tags, and those tags can be used to apply discounts and promotions.

## Accounts vs Customers

Accounts is the next generation of [Customers](/docs/customer-management/customers). Customers are not going
anywhere, but accounts offers more capabilities. We recommend using Accounts for any of your new use cases.

| Feature                                                                                     | Customers | Accounts |
|---------------------------------------------------------------------------------------------|-----------|----------|
| B2C Accounts                                                                                | ✅         | ✅        |
| Family Accounts                                                                             | ⛔️        | ✅        |
| B2B Accounts                                                                                | ⛔️        | ✅        |
| Authentication: Shopper impersonation                                                       | ⛔️        | ✅        |
| Authentication: OpenID support                                                              | ✅         | ✅        |
| Authentication: One time passwords, and password reset                                      | ⛔️        | ✅        |
| Authentication: Configurable token expiry                                                   | ⛔️        | ✅        |
| Cart association                                                                            | ✅         | ✅        |
| Shopper specific Promotions                                                                 | Limited   | ✅        |
| Shopper specific Catalogs                                                                   | ✅         | ✅        |
| Addresses                                                                                   | ✅         | ✅        |
| [Personal Data Support (GDPR,CCPA,...)](/docs/api/personal-data/personal-data-introduction) | ✅         | ✅        |

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"BearerToken"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Account Members

An `Account Member` resource is a user that you can add to accounts using account memberships.

Account members API is read only, and you cannot add users using this API. There is a 1 to 1 correspondence between User Authentication Info and an Account Member, the corresponding objects have the same id. You must use the `user_authentication_info` object to create users in the authentication realm of account authentication settings. For more information on adding account members, see the [Adding Accounts and Account Members](/guides/How-To/Accounts/add-account-and-member) section.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Account Membership Settings

Account Membership Settings allow Account Members to be associated to, at most, N accounts at a time. You can set this value to any number up to 10,000. The default value is 10,000.

This setting is only applied to new account memberships. If an account member is added to 3 accounts, and the setting is reduced to 1, the account member remains in the 3 accounts and can no longer be added to more.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Account Membership

The `Account Membership` resource represents the relationship between an account and an account member. This relationship is many to many. Each account can have multiple account members, and each account member can be a member of multiple accounts.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Account Tags

Account Tags are custom labels or metadata that can be attached to accounts to help organize and filter them based on specific attributes or criteria.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Accounts

An Account represents the entity that participates in a Commerce transaction. Accounts can have Carts, Orders, Subscriptions, and Addresses.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Add Account Tags

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Add Account Tags"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/accounts/{accountID}/relationships/account-tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Add Account Tags onto an Account. Please note that after adding a tag to an account, the account member token should be regenerated to reflect the updated account status, allowing other services to react accordingly. See [Account Management Authentication Token](/docs/api/accounts/post-v-2-account-members-tokens).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for the related Account Tag.","type":"string","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"description":"Specifies the type of the resource object.","type":"string","const":"account_tag"}},"title":"AccountTagsRelationshipIdentifier"}}},"title":"AddAccountTagsOnAccount"},"examples":{"Add Example":{"summary":"Add an Account Tag","value":{"data":[{"type":"account_tag","id":"030693ce-39ad-4f4c-9941-d2d596478e94"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for the related Account Tag.","type":"string","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"description":"Specifies the type of the resource object.","type":"string","const":"account_tag"}},"title":"AccountTagsRelationshipIdentifier"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/relationships/account-tags"}}}},"title":"AccountTagsRelationshipResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"account membership with the given account id and account member id already exists"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create an Account Tag

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Account Tag"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/account-tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create an Account Tag

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Specifies the type of the resource object, use `account_tag` for Account Tags.","type":"string","const":"account_tag"},"name":{"type":"string","description":"Specifies the name of the account tag.","example":"account-name-tag"},"description":{"type":"string","description":"Describes the account tag."}},"title":"AccountTag"}},"required":["data"]},"examples":{"Create Example":{"summary":"Create an Account Tag","value":{"data":{"type":"account_tag","name":"Account Name","description":"Account Description"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the resource object, use `account_tag` for Account Tags.","type":"string","const":"account_tag"},"name":{"type":"string","description":"Specifies the name of the account tag.","example":"account-name-tag"},"description":{"type":"string","description":"Describes the account tag."}},"title":"AccountTag"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-tags/deb6b25f-8451-4211-9a22-95610333df23"}}}}}],"title":"AccountTagResponse"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"account membership with the given account id and account member id already exists"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete an Account Tag

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an Account Tag"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/account-tags/{tag_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete an Account Tag

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"tag_id","description":"The ID of the Account Tag.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete an Account Membership

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an Account Membership"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/accounts/{accountID}/account-memberships/{membershipID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a membership from an account

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The unique identifier of the account that the account member is associated with.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"membershipID","in":"path","description":"The unique identifier of the account membership to update the details of the account member.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete an Account

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an Account"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/accounts/{accountID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a specific account within a store

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Account Tag

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Account Tag"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/account-tags/{tag_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get an Account Tag

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"tag_id","description":"The ID of the Account Tag.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the resource object, use `account_tag` for Account Tags.","type":"string","const":"account_tag"},"name":{"type":"string","description":"Specifies the name of the account tag.","example":"account-name-tag"},"description":{"type":"string","description":"Describes the account tag."}},"title":"AccountTag"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-tags/deb6b25f-8451-4211-9a22-95610333df23"}}}}}],"title":"AccountTagResponse"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Account's Tags Relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Account's Tags Relationship"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/accounts/{accountID}/relationships/account-tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of Account Tags on an Account

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for the related Account Tag.","type":"string","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"description":"Specifies the type of the resource object.","type":"string","const":"account_tag"}},"title":"AccountTagsRelationshipIdentifier"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/relationships/account-tags"}}}},"title":"AccountTagsRelationshipResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a List of Account Memberships of Account Member

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a List of Account Memberships of Account Member"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/account-members/{accountMemberId}/account-memberships"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can also use `include=account` to retrieve details about the accounts associated with the account memberships. For more information see [including resources](/guides/Getting-Started/includes).

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

### Filtering

The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) account memberships.

| Operator | Description |
| :--- | :--- |
| `eq` | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |
| `like` | Checks if the operand contains the specified string. You can use wildcard characters in operand. |

| Attribute | Type | Operator | Example |
| :--- | :--- | :--- | :--- |
| `account_member_id` | `string` | `eq` / `like` | `eq(account_member_id,00000000-0000-1000-8000-0000000)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","description":"Specifies the filter attributes.","required":false,"schema":{"type":"string","format":"string","example":"ilike(name,\"*swan*\")"}},{"name":"include","in":"query","description":"Parameter to retrieve more information about any related resources like accounts.","schema":{"type":"string","example":"account"}},{"name":"accountMemberId","in":"path","description":"The ID of the account member for which you want to list the memberships.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sort","in":"query","description":"Specifies the order in which account memberships will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).","required":false,"schema":{"type":["string"],"enum":["created_at","-created_at","id","-id","updated_at","-updated_at"],"x-enumDescriptions":{"created_at":"Sort in increasing order of creation","-created_at":"Sort in decreasing order of creation","id":"Sort in increasing order of ID","-id":"Sort in decreasing order of ID","updated_at":"Sort in increasing order of last update","-updated_at":"Sort in decreasing order of last update"}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"description":"Represents the unique identifier for the account membership.","type":"string","format":"uuid","example":"24e939f6-178f-497b-9d64-5bf2b5a70a2e"},"type":{"description":"Represents the type of the object returned.","type":"string","const":"account_membership"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"Specifies the ID of the account.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"Specifies the type of the Account.","type":"string","const":"account"}}}}}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships/24e939f6-178f-497b-9d64-5bf2b5a70a2e"}}}},"title":"AccountMembershipResponseUsingAccountMemberId"},{"type":"object","properties":{"account_member_id":{"description":"The unique identifier for an Account Member.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"}}}]}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25"},"last":{"description":"Always `null` if there is only one page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25"},"next":{"description":"Always `null` if there is only one page.","type":"string","example":null},"prev":{"description":"Always `null` if the user is on the first page.","type":"string","example":null}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Account Member

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Account Member"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/account-members/{accountMemberID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get an account member from your store

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountMemberID","in":"path","description":"The unique identifier of the account member that you want to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"id":{"description":"The unique identifier for the account member.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"The type of the object that is returned.","type":"string","const":"account_member"},"name":{"description":"The name of the account member.","type":"string","example":"Ron Swanson"},"given_name":{"description":"The given name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Ron"},"middle_name":{"description":"The middle name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Ulysses"},"family_name":{"description":"The family name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Swanson"},"email":{"description":"The email address of the account member.","type":"string","format":"email","example":"ron@swanson.com"}},"title":"AccountMember"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-members/908f7849-60da-4e4a-a3b1-51d4cbe3b953"}}}}}],"title":"AccountMemberResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-members/deb6b25f-8451-4211-9a22-95610333df23"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Account Members

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Account Members"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/account-members"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all account members contained within your store.

    ### Filtering

    The following operators and attributes are available for
[filtering](/guides/Getting-Started/filtering) account members.

| Attribute | Type | Operator | Example | | :--- | :--- | :--- | :--- | | `email`       | `string` | `ilike`           | `ilike(email,'ronswanson@example.com')` | | `name`        | `string` | `ilike`           | `ilike(name,'*swan*')`                  | | `given_name`  | `string` | `ilike`/`is_null` | `ilike(given_name,'ron*')`              | | `middle_name` | `string` | `ilike`/`is_null` | `is_null(middle_name)`                  | | `family_name` | `string` | `ilike`/`is_null` | `is_null(family_name)`                  |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"filter","in":"query","description":"Specifies the filter attributes.","required":false,"schema":{"type":"string","format":"string","example":"ilike(name,\"*swan*\")"}},{"name":"sort","in":"query","description":"Specifies the order in which account members will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).","required":false,"schema":{"type":"string","enum":["created_at","-created_at","email","-email","id","-id","name","-name","updated_at","-updated_at"],"x-enumDescriptions":{"created_at":"Sort in increasing order of creation","-created_at":"Sort in decreasing order of creation","email":"Sort in increasing order of email","-email":"Sort in decreasing order of email","id":"Sort in increasing order of ID","-id":"Sort in decreasing order of ID","name":"Sort in increasing order of name","-name":"Sort in decreasing order of name","updated_at":"Sort in increasing order of last update","-updated_at":"Sort in decreasing order of last update"},"example":"id"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"description":"The unique identifier for the account member.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"The type of the object that is returned.","type":"string","const":"account_member"},"name":{"description":"The name of the account member.","type":"string","example":"Ron Swanson"},"given_name":{"description":"The given name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Ron"},"middle_name":{"description":"The middle name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Ulysses"},"family_name":{"description":"The family name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Swanson"},"email":{"description":"The email address of the account member.","type":"string","format":"email","example":"ron@swanson.com"}},"title":"AccountMember"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-members/908f7849-60da-4e4a-a3b1-51d4cbe3b953"}}}}}],"title":"AccountMemberResponse"}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/account-members?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/account-members?page[offset]=0&page[limit]=25"},"last":{"description":"Always `null` if there is only one page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/account-members?page[offset]=0&page[limit]=25"},"next":{"description":"Always `null` if there is only one page.","type":"string","example":null},"prev":{"description":"Always `null` if the user is on the first page.","type":"string","example":null}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":{"errors":[{"title":"Unauthorized","status":"401"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Account Membership

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Account Membership"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/accounts/{accountID}/account-memberships/{membershipID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get an account membership from an account in your store.

You can also use `include=account_member` to retrieve details about the account member associated with this account membership. With this option, you can get more information about the account member such as name and email in a single request. For more information see [including resources](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"include","in":"query","description":"Parameter to retrieve more information about any related resources like account members.","schema":{"type":"string","example":"account_member"}},{"name":"accountID","in":"path","description":"The unique identifier of the account that the account member is associated with.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"membershipID","in":"path","description":"The unique identifier of the account membership to update the details of the account member.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"Represents the unique identifier for the account membership.","type":"string","format":"uuid","example":"24e939f6-178f-497b-9d64-5bf2b5a70a2e"},"type":{"description":"Represents the type of the object returned.","type":"string","const":"account_membership"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account_member":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"Specifies the ID of the account member.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"Specifies the type of the account member.","type":"string","const":"account_member"}}}}}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships/24e939f6-178f-497b-9d64-5bf2b5a70a2e"}}}},"title":"AccountMembershipResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/5ac48b3b-825d-43a3-9fcd-962230629d5e"}}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a List of Unassigned Account Members

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a List of Unassigned Account Members"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/accounts/{accountID}/account-memberships/unassigned-account-members"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this resource to get a list of all account members that are not assigned to an account.

### Filtering

The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) unassigned account members.

| Operator | Description   |
| :------- | :--------------------------------------------------------------------------------------------------- |
| `eq`     | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |
| `like`   | Checks if the operand contains the specified string. You can use wildcard characters in operand.     |

| Attribute | Type     | Operator      | Example |
| :-------- | :------- | :------------ | :--------------------------------- |
| `email`   | `string` | `eq` / `like` | `eq(email,ronswanson@example.com)` |
| `name`    | `string` | `eq` / `like` | `like(name,*swan*)` |

:::note

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"filter","in":"query","description":"Specifies the filter attributes.","required":false,"schema":{"type":"string","format":"string","example":"ilike(name,\"*swan*\")"}},{"name":"accountID","in":"path","description":"The ID of the account for which you want to get the list of unassigned account members.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sort","in":"query","description":"Specifies the order in which unassigned account members will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).","required":false,"schema":{"type":"string","enum":["created_at","-created_at","updated_at","updated_at"],"x-enumDescriptions":{"created_at":"Sort in increasing order of creation","-created_at":"Sort in decreasing order of creation","updated_at":"Sort in increasing order of last update","-updated_at":"Sort in decreasing order of last update"},"example":"id"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"description":"The unique identifier for the account member.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"The type of the object that is returned.","type":"string","const":"account_member"},"name":{"description":"The name of the account member.","type":"string","example":"Ron Swanson"},"given_name":{"description":"The given name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Ron"},"middle_name":{"description":"The middle name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Ulysses"},"family_name":{"description":"The family name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Swanson"},"email":{"description":"The email address of the account member.","type":"string","format":"email","example":"ron@swanson.com"}},"title":"AccountMember"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-members/908f7849-60da-4e4a-a3b1-51d4cbe3b953"}}}}}],"title":"AccountMemberResponse"}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/unassigned-account-members?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/unassigned-account-members?page[offset]=0&page[limit]=25"},"last":{"description":"Always `null` if there is only one page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/unassigned-account-members?page[offset]=0&page[limit]=25"},"next":{"description":"Always `null` if there is only one page.","type":"string","example":null},"prev":{"description":"Always `null` if the user is on the first page.","type":"string","example":null}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"account membership with the given account id and account member id already exists"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Account Memberships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Account Memberships"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/accounts/{accountID}/account-memberships"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can also use `include=account_member` to retrieve details about the account members associated with the account memberships. With this option, you can get more information about the account members such as name and email in a single request. For more information see [including resources](/guides/Getting-Started/includes).

### Filtering

The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) account memberships.

| Operator | Description |
| :--- | :--- |
| `eq` | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |
| `like` | Checks if the operand contains the specified string. You can use wildcard characters in operand. |

| Attribute | Type | Operator | Example |
| :--- | :--- | :--- | :--- |
| `account_member_id` | `string` | `eq` / `like` | `eq(account_member_id,00000000-0000-1000-8000-0000000)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","description":"Specifies the filter attributes.","required":false,"schema":{"type":"string","format":"string","example":"ilike(name,\"*swan*\")"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"include","in":"query","description":"Parameter to retrieve more information about any related resources like account members.","schema":{"type":"string","example":"account_member"}},{"name":"accountID","in":"path","description":"The ID of the account for which you want to get the list of unassigned account members.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sort","in":"query","description":"Specifies the order in which account memberships will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).","required":false,"schema":{"type":"string","enum":["created_at","-created_at","updated_at","-updated_at","id","-id"],"x-enumDescriptions":{"created_at":"Sort in increasing order of creation","-created_at":"Sort in decreasing order of creation","id":"Sort in increasing order of ID","-id":"Sort in decreasing order of ID","updated_at":"Sort in increasing order of last update","-updated_at":"Sort in decreasing order of last update"},"example":"id"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"description":"Represents the unique identifier for the account membership.","type":"string","format":"uuid","example":"24e939f6-178f-497b-9d64-5bf2b5a70a2e"},"type":{"description":"Represents the type of the object returned.","type":"string","const":"account_membership"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account_member":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"Specifies the ID of the account member.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"Specifies the type of the account member.","type":"string","const":"account_member"}}}}}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships/24e939f6-178f-497b-9d64-5bf2b5a70a2e"}}}},"title":"AccountMembershipResponse"},{"type":"object","properties":{"account_member_id":{"description":"The unique identifier for an Account Member.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"}}}]}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25"},"last":{"description":"Always `null` if there is only one page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships?page[offset]=0&page[limit]=25"},"next":{"description":"Always `null` if there is only one page.","type":"string","example":null},"prev":{"description":"Always `null` if the user is on the first page.","type":"string","example":null}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Account

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Account"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/accounts/{accountID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

View a specific account contained within your store

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account`.","const":"account"},"name":{"type":"string","description":"Specifies the name of the account.","example":"acc-name"},"legal_name":{"type":["string","null"],"description":"Specifies the legal name of the account.","example":"acc-legal-name"},"registration_id":{"type":["string","null"],"description":"Specifies the registration ID. If specified, this field is checked for uniqueness.","example":"reg-id"},"external_ref":{"type":["string","null"],"description":"The unique attribute associated with the account. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`.","example":"ext-ref"}},"required":["type","name"],"title":"Account"},{"type":"object","properties":{"parent_id":{"type":["string","null"],"format":"uuid","readOnly":true,"description":"Specifies the ID of the parent account.","example":"96b1f750-55d3-4768-a3f8-adffba694a2c"}},"title":"ReadOnlyParentId"},{"type":"object","properties":{"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this realm. For more information, see [The meta object](https://elasticpath.dev/docs/commerce-cloud/accounts/using-account-management-api/account-management-api-overview#the-meta-object) section.","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account_tags":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for an Account Tag.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"type":{"type":"string","const":"account_tag"}}}}},"description":"Tags associated with the account."},"ancestors":{"type":"array","items":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"type":{"type":"string","const":"account"}}}},"description":"All parent accounts in the hierarchy in sorted order (root first)."}},"parent":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"account"},"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"}}}}}}}}}],"title":"AccountResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23"}}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get All Accounts

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get All Accounts"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/accounts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to Get all accounts.

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

### Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) accounts:

| Attribute         | Operators                     | Example                                                       |
|-------------------|-------------------------------|---------------------------------------------------------------|
| `id`              | `lt`,`le`,`eq`,`gt`,`ge`,`in` | `eq(id,3fa85f64-5717-4562-b3fc-2c963f66afa6)`                 |
| `created_at`      | `lt`,`le`,`eq`,`gt`,`ge`      | `ge(created_at,2024-04-29T00:00:00.000Z)`                     |
| `updated_at`      | `lt`,`le`,`eq`,`gt`,`ge`      | `le(updated_at,2024-04-29T00:00:00.000Z)`                     |
| `name`            | `eq`,`like`                   | `like(name,*swan*)`                                           |
| `legal_name`      | `eq`,`like`                   | `like(legal_name,*swan*)`                                     |
| `registration_id` | `eq`,`like`                   | `like(registration_id,00000000-0000-1000-8000-*)`             |
| `external_ref`    | `eq`,`like`,`in`              | `like(external_ref,16be*)`                                    |
| `account_tags`    | `contains`                    | `contains(account_tags,26beb787-be6e-40c3-bbae-9c645820b075)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","description":"Specifies the filter attributes.","required":false,"schema":{"type":"string","format":"string","example":"ilike(name,\"*swan*\")"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"sort","in":"query","description":"Specifies the order in which accounts will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).","required":false,"schema":{"type":"string","enum":["created_at","-created_at","id","-id","name","-name","updated_at","-updated_at"],"example":"id","x-enumDescriptions":{"created_at":"Sort in increasing order of creation","-created_at":"Sort in decreasing order of creation","id":"Sort in increasing order of ID","-id":"Sort in decreasing order of ID","name":"Sort in increasing order of name","-name":"Sort in decreasing order of name","updated_at":"Sort in increasing order of last update","-updated_at":"Sort in decreasing order of last update"}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account`.","const":"account"},"name":{"type":"string","description":"Specifies the name of the account.","example":"acc-name"},"legal_name":{"type":["string","null"],"description":"Specifies the legal name of the account.","example":"acc-legal-name"},"registration_id":{"type":["string","null"],"description":"Specifies the registration ID. If specified, this field is checked for uniqueness.","example":"reg-id"},"external_ref":{"type":["string","null"],"description":"The unique attribute associated with the account. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`.","example":"ext-ref"}},"required":["type","name"],"title":"Account"},{"type":"object","properties":{"parent_id":{"type":["string","null"],"format":"uuid","readOnly":true,"description":"Specifies the ID of the parent account.","example":"96b1f750-55d3-4768-a3f8-adffba694a2c"}},"title":"ReadOnlyParentId"},{"type":"object","properties":{"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this realm. For more information, see [The meta object](https://elasticpath.dev/docs/commerce-cloud/accounts/using-account-management-api/account-management-api-overview#the-meta-object) section.","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account_tags":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for an Account Tag.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"type":{"type":"string","const":"account_tag"}}}}},"description":"Tags associated with the account."},"ancestors":{"type":"array","items":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"type":{"type":"string","const":"account"}}}},"description":"All parent accounts in the hierarchy in sorted order (root first)."}},"parent":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"account"},"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"}}}}}}}}}],"title":"AccountResponse"},{"type":"object","properties":{"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23"}}}}}]}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts?page[offset]=0&page[limit]=25"},"last":{"description":"Always `null` if there is only one page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts?page[offset]=0&page[limit]=25"},"next":{"description":"Always `null` if there is only one page.","type":"string","example":null},"prev":{"description":"Always `null` if the user is on the first page.","type":"string","example":null}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":{"errors":[{"title":"Unauthorized","status":"401"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Account Authentication Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Account Authentication Settings"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/account-authentication"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to view account authentication settings

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account_authentication_settings`.","const":"account_authentication_settings"},"enable_self_signup":{"description":"Set to `true` to enable self signup.","type":"boolean","example":true},"auto_create_account_for_account_members":{"description":"This will automatically create an account for each new account member, using the account member’s name as the account name.","type":"boolean","example":true},"account_member_self_management":{"description":"Whether a user with an [Account Management Authentication Token](/docs/api/accounts/post-v-2-account-members-tokens) can update their own account member details. By default, this is `disabled`. Set to `update_only` if you want the user to be able to update their own account member details (e.g., name, email, and if applicable their username and password). The user can update their own account member details by updating their [User Authentication Info](/docs/authentication/single-sign-on/user-authentication-info-api/update-a-user-authentication-info) using the `account_member_id` retrieved from the `meta` in the response of [Generating an Account Management Authentication Token](/docs/api/accounts/post-v-2-account-members-tokens) as the `id` and find the authentication credentials to update by calling the [Get All User Authentication Password Profile Info](/docs/authentication/single-sign-on/user-authentication-password-profiles-api/get-all-user-authentication-password-profile-info) endpoint.","type":"string","default":"disabled","enum":["disabled","update_only"]},"account_management_authentication_token_timeout_secs":{"description":"The expiry time for Account Management Authentication Token in seconds. If you want to implement idle timout for you application, see [Implementing Idle Timeout](/guides/How-To/Accounts/implement-idle-timeout)","type":"integer","default":86400,"example":86400}},"title":"AccountAuthenticationSettings"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"relationships":{"type":"object","properties":{"authentication_realm":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The ID of the authentication realm entity.","type":"string","format":"uuid","example":"3418c54e-d768-42c1-a9db-d7afd2a18452"},"type":{"description":"The type of the authentication realm entity.","type":"string","const":"authentication_realm"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/authentication-realms/3418c54e-d768-42c1-a9db-d7afd2a18452"}}}}}}}}},"meta":{"type":"object","properties":{"client_id":{"description":"The client ID to be used in Single Sign On authentication flows for accounts.","type":"string","example":"account-management"}}}}}]},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account_authentication_settings"}}}},"title":"AccountAuthenticationSettingsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":{"errors":[{"title":"Unauthorized","status":"401"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Account Membership Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Account Membership Settings"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/account-membership"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to get all account membership settings.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account_membership_setting`.","example":"account_membership_setting","enum":["account_membership_setting"]},"membership_limit":{"type":"integer","description":"The number of accounts an account member can be associated with. You can set this value to any number up to 10,000.","example":100}}}},"title":"AccountMembershipSettings"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":{"errors":[{"title":"Unauthorized","status":"401"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## List Account Tags

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Account Tags"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/account-tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of Account Tags

## Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) Account Tags:

| Attribute        | Operators                     | Example                                       |
|------------------|-------------------------------|-----------------------------------------------|
| `id`             | `lt`,`le`,`eq`,`gt`,`ge`,`in` | `eq(id,3fa85f64-5717-4562-b3fc-2c963f66afa6)` |
| `created_at`     | `lt`,`le`,`eq`,`gt`,`ge`      | `ge(created_at,2024-04-29T00:00:00.000Z)`     |
| `updated_at`     | `lt`,`le`,`eq`,`gt`,`ge`      | `le(updated_at,2024-04-29T00:00:00.000Z)`     |
| `name`           | `eq`,`like`                   | `eq(name,AccountName)`                        |

## Sorting
The following attributes are available for sorting. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with `-`, for example, `-updated_at`. The default sort order is `created_at` in descending order.
- `id`
- `created_at`
- `updated_at`
- `name`

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","description":"Specifies the filter attributes.","required":false,"schema":{"type":"string","format":"string","example":"ilike(name,\"*swan*\")"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"sort","in":"query","description":"Specifies the order in which account tags will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).","required":false,"schema":{"type":["string"],"enum":["created_at","-created_at","id","-id","updated_at","-updated_at"],"x-enumDescriptions":{"created_at":"Sort in increasing order of creation","-created_at":"Sort in decreasing order of creation","id":"Sort in increasing order of ID","-id":"Sort in decreasing order of ID","updated_at":"Sort in increasing order of last update","-updated_at":"Sort in decreasing order of last update"},"example":"id"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the resource object, use `account_tag` for Account Tags.","type":"string","const":"account_tag"},"name":{"type":"string","description":"Specifies the name of the account tag.","example":"account-name-tag"},"description":{"type":"string","description":"Describes the account tag."}},"title":"AccountTag"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-tags/deb6b25f-8451-4211-9a22-95610333df23"}}}}}],"title":"AccountTagResponse"}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts?page[offset]=0&page[limit]=25"},"last":{"description":"Always `null` if there is only one page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts?page[offset]=0&page[limit]=25"},"next":{"description":"Always `null` if there is only one page.","type":"string","example":null},"prev":{"description":"Always `null` if the user is on the first page.","type":"string","example":null}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Generate an Account Management Authentication Token

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Generate an Account Management Authentication Token"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/account-members/tokens"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Commerce provides authentication tokens for anyone using the Account Management APIs, including accounts and account members.

For each element in the list returned by the account member authentication API, a token value is returned. In order for a shopper to authenticate as the account, this value should be set as the `EP-Account-Management-Authentication-Token` header when calling Commerce. This header grants access to additional resources associated with the account, such as [carts](/docs/api/carts/account-cart-associations), [orders](/docs/api/carts/orders), [catalogs with associated rules](/docs/api/pxm/catalog/rules), and [addresses](/docs/api/addresses/addresses-introduction).

The set of permissions available to a shopper using an Account Management Authentication token is documented in [Permissions](/docs/authentication/tokens/permissions)

Commerce provides authentication tokens for an account and an account member using:

- OpenID Connect
- Username and password
- Self signup
- One-time password token
- Switch account token

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","oneOf":[{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `oidc`.","type":"string","const":"oidc"},"oauth_authorization_code":{"description":"Specifies the code returned from the OpenID Connect Provider authentication.","type":"string","example":"c2490f06-6d8e-4927-99aa-4bf02b419e96"},"oauth_redirect_uri":{"description":"Specifies the URL of the front-end that handles the callback of the token.","type":"string","format":"uri","example":"https://example-store.com/oauth2/callback"},"oauth_code_verifier":{"description":"Specifies the Proof Key for Code Exchange (PKCE) code verifier corresponding to the code challenge supplied to the authorization endpoint. For more information about code verifier and challenge, see Generating a [Code Verifier and Challenge](https://elasticpath.dev/docs/commerce-cloud/authentication/single-sign-on/get-single-sign-on-customer-token#generate-proof-key-for-code-exchange-pkce-parameters).","type":"string","example":"0E934PurR8ExVg6Pj7T4kQewxKzWSfSFG5d15FGfww8"}}}],"required":["type","authentication_mechanism","oauth_authorization_code","oauth_redirect_uri","oauth_code_verifier"],"title":"OpenIDConnectRequest"},{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `password`.","type":"string","const":"password"},"password_profile_id":{"description":"The password profile ID. For more information, see [password profiles page](https://elasticpath.dev/docs/commerce-cloud/authentication/single-sign-on/password-profiles-api/overview).","type":"string","format":"uuid","example":"c2490f06-6d8e-4927-99aa-4bf02b419e96"},"username":{"description":"The username.","type":"string","example":"username"},"password":{"description":"The password.","type":"string","format":"password","example":"pa$$word"}}}],"required":["type","authentication_mechanism","password_profile_id","username","password"],"title":"PasswordRequest"},{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `passwordless`.","type":"string","const":"passwordless"},"password_profile_id":{"description":"The password profile ID. For more information, see [password profiles page](https://elasticpath.dev/docs/commerce-cloud/authentication/single-sign-on/password-profiles-api/overview).","type":"string","format":"uuid","example":"c2490f06-6d8e-4927-99aa-4bf02b419e96"},"username":{"description":"The username.","type":"string","example":"jane.doe@gmail.com"},"one_time_password_token":{"description":"The one-time password token.","type":"string","example":"abd1g5"}}}],"required":["type","authentication_mechanism","password_profile_id","username","one_time_password_token"],"title":"PasswordlessRequest"},{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `self_signup`.","type":"string","const":"self_signup"},"password_profile_id":{"description":"The password profile ID. For more information, see [password profiles page](https://elasticpath.dev/docs/commerce-cloud/authentication/single-sign-on/password-profiles-api/overview).","type":"string","format":"uuid","example":"c2490f06-6d8e-4927-99aa-4bf02b419e96"},"username":{"description":"The username.","type":"string","example":"username"},"password":{"description":"The password.","type":"string","format":"password","example":"pa$$word"},"name":{"description":"The name.","type":"string","example":"Ron Swanson"},"given_name":{"description":"The given name for the user.","type":["string","null"],"example":"Ron"},"middle_name":{"description":"The middle name for the user.","type":["string","null"],"example":"Ulysses"},"family_name":{"description":"The family name for the user.","type":["string","null"],"example":"Swanson"},"email":{"description":"The email.","type":"string","format":"email","example":"ron@swanson.com"}}}],"required":["type","authentication_mechanism","password_profile_id","username","password","name","email"],"title":"SelfSignupRequest"},{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}}}],"required":["type","authentication_mechanism"],"title":"SwitchingAccountRequest"}],"discriminator":{"propertyName":"authentication_mechanism","mapping":{"oidc":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `oidc`.","type":"string","const":"oidc"},"oauth_authorization_code":{"description":"Specifies the code returned from the OpenID Connect Provider authentication.","type":"string","example":"c2490f06-6d8e-4927-99aa-4bf02b419e96"},"oauth_redirect_uri":{"description":"Specifies the URL of the front-end that handles the callback of the token.","type":"string","format":"uri","example":"https://example-store.com/oauth2/callback"},"oauth_code_verifier":{"description":"Specifies the Proof Key for Code Exchange (PKCE) code verifier corresponding to the code challenge supplied to the authorization endpoint. For more information about code verifier and challenge, see Generating a [Code Verifier and Challenge](https://elasticpath.dev/docs/commerce-cloud/authentication/single-sign-on/get-single-sign-on-customer-token#generate-proof-key-for-code-exchange-pkce-parameters).","type":"string","example":"0E934PurR8ExVg6Pj7T4kQewxKzWSfSFG5d15FGfww8"}}}],"required":["type","authentication_mechanism","oauth_authorization_code","oauth_redirect_uri","oauth_code_verifier"],"title":"OpenIDConnectRequest"},"password":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `password`.","type":"string","const":"password"},"password_profile_id":{"description":"The password profile ID. For more information, see [password profiles page](https://elasticpath.dev/docs/commerce-cloud/authentication/single-sign-on/password-profiles-api/overview).","type":"string","format":"uuid","example":"c2490f06-6d8e-4927-99aa-4bf02b419e96"},"username":{"description":"The username.","type":"string","example":"username"},"password":{"description":"The password.","type":"string","format":"password","example":"pa$$word"}}}],"required":["type","authentication_mechanism","password_profile_id","username","password"],"title":"PasswordRequest"},"passwordless":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `passwordless`.","type":"string","const":"passwordless"},"password_profile_id":{"description":"The password profile ID. For more information, see [password profiles page](https://elasticpath.dev/docs/commerce-cloud/authentication/single-sign-on/password-profiles-api/overview).","type":"string","format":"uuid","example":"c2490f06-6d8e-4927-99aa-4bf02b419e96"},"username":{"description":"The username.","type":"string","example":"jane.doe@gmail.com"},"one_time_password_token":{"description":"The one-time password token.","type":"string","example":"abd1g5"}}}],"required":["type","authentication_mechanism","password_profile_id","username","one_time_password_token"],"title":"PasswordlessRequest"},"self_signup":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `self_signup`.","type":"string","const":"self_signup"},"password_profile_id":{"description":"The password profile ID. For more information, see [password profiles page](https://elasticpath.dev/docs/commerce-cloud/authentication/single-sign-on/password-profiles-api/overview).","type":"string","format":"uuid","example":"c2490f06-6d8e-4927-99aa-4bf02b419e96"},"username":{"description":"The username.","type":"string","example":"username"},"password":{"description":"The password.","type":"string","format":"password","example":"pa$$word"},"name":{"description":"The name.","type":"string","example":"Ron Swanson"},"given_name":{"description":"The given name for the user.","type":["string","null"],"example":"Ron"},"middle_name":{"description":"The middle name for the user.","type":["string","null"],"example":"Ulysses"},"family_name":{"description":"The family name for the user.","type":["string","null"],"example":"Swanson"},"email":{"description":"The email.","type":"string","format":"email","example":"ron@swanson.com"}}}],"required":["type","authentication_mechanism","password_profile_id","username","password","name","email"],"title":"SelfSignupRequest"},"account_management_authentication_token":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the object. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}},"title":"AccountManagementAuthenticationToken"},{"type":"object","properties":{"authentication_mechanism":{"description":"Species the authentication mechanism. You must use `account_management_authentication_token`.","type":"string","const":"account_management_authentication_token"}}}],"required":["type","authentication_mechanism"],"title":"SwitchingAccountRequest"}}}}},"required":["data"]},"examples":{"OpenID Connect":{"value":{"data":{"type":"account_management_authentication_token","authentication_mechanism":"oidc","oauth_authorization_code":"c2490f06-6d8e-4927-99aa-4bf02b419e96","oauth_redirect_uri":"https://example-store.com/oauth2/callback","oauth_code_verifier":"0E934PurR8ExVg6Pj7T4kQewxKzWSfSFG5d15FGfww8"}}},"Username and Password":{"value":{"data":{"type":"account_management_authentication_token","authentication_mechanism":"password","password_profile_id":"161292d3-c105-490f-8798-0ec71cd5a272","username":"john.doe","password":"password"}}},"One-time Password Token":{"value":{"data":{"type":"account_management_authentication_token","authentication_mechanism":"passwordless","password_profile_id":"161292d3-c105-490f-8798-0ec71cd5a272","username":"john.doe","one_time_password_token":"abc123"}}},"Self Signup":{"value":{"data":{"type":"account_management_authentication_token","authentication_mechanism":"self_signup","password_profile_id":"161292d3-c105-490f-8798-0ec71cd5a272","username":"john.doe@gmail.com","password":"password","name":"john","email":"john.doe@gmail.com"}}},"Switch account tokens":{"value":{"data":{"type":"account_management_authentication_token","authentication_mechanism":"account_management_authentication_token"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"description":"Specifies the type of the object.","type":"string","const":"account_management_authentication_token"},"account_name":{"description":"The name of the account that this token grants access to.","type":"string","example":"acc-name-1"},"account_id":{"description":"The ID of the account that this token grants access to.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"token":{"description":"The JWT authentication token that the shopper uses as the `EP-Account-Management-Authentication-Token` header [in all other endpoints](https://elasticpath.dev/docs/commerce-cloud/authentication/tokens/account-management-authentication-token).","type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOiIyMDIxLTAzLTE2VDE5OjM2OjExLjA3MFoiLCJpYXQiOiIyMDIxLTAzLTE1VDE5OjM2OjExLjA3MFoiLCJzY29wZSI6IjFjNDVlNGVjLTI2ZTAtNDA0My04NmU0LWMxNWI5Y2Y5ODVhMyIsInN1YiI6IjFjNDVlNGVjLTI2ZTAtNDA0My04NmU0LWMxNWI5Y2Y5ODVhMiJ9.ytQ3UutTl_RJ8NiB1xN29Ta23p-FXsYOhcUM7MUQ4CM"},"expires":{"description":"The epoch time that this token expires at. The time is set to 24 hours after the token is generated.","type":"string","format":"date-time","example":"2021-03-16T19:36:11.070Z"}},"title":"AccountManagementAuthenticationTokenResponse"}},"meta":{"allOf":[{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},{"type":"object","properties":{"account_member_id":{"type":"string","format":"uuid","description":"The unique identifier for the Account Member that authenticated. This is useful if `account_member_self_management` is enabled in [Account Authentication Settings](/docs/api/accounts/get-v-2-settings-account-authentication), so that the user can update details for their account.","example":"f5d08d48-bbc8-4f61-818f-a78583045f56"}},"title":"MetaAccountMemberId"}]},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/account-members/tokens?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/account-members/tokens?page[offset]=0&page[limit]=25"},"last":{"description":"Always `null` if there is only one page.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/account-members/tokens?page[offset]=0&page[limit]=25"},"next":{"description":"Always `null` if there is only one page.","type":"string","example":null},"prev":{"description":"Always `null` if the user is on the first page.","type":"string","example":null}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":{"errors":[{"title":"Unauthorized","status":"401"}]}}}}}},"403":{"description":"Forbidden Error","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"forbidden-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"forbidden"}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unprocessable-entity":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"store id mismatch"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create an Account Membership

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Account Membership"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/accounts/{accountID}/account-memberships"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::caution

You can only create up to 1000 account memberships in an account.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The unique identifier of the account that the account is associated with.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"account_member_id":{"type":"string","format":"uuid","description":"Specifies the unique identifier of the account member that the membership is associated with.","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"type":"string","const":"account_membership","description":"Specifies the type of the object. Set this value to `account_membership`."}},"title":"AccountMembership"}}},"examples":{"Create account membership":{"value":{"data":{"type":"account_membership","account_member_id":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"Represents the unique identifier for the account membership.","type":"string","format":"uuid","example":"24e939f6-178f-497b-9d64-5bf2b5a70a2e"},"type":{"description":"Represents the type of the object returned.","type":"string","const":"account_membership"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account_member":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"Specifies the ID of the account member.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"Specifies the type of the account member.","type":"string","const":"account_member"}}}}}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships/24e939f6-178f-497b-9d64-5bf2b5a70a2e"}}}},"title":"AccountMembershipResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/5ac48b3b-825d-43a3-9fcd-962230629d5e"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"account membership with the given account id and account member id already exists"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unprocessable-entity":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"store id mismatch"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create an Account

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Account"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/accounts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

With the account creation endpoint, you have the ability to create accounts which can optionally have another account as a parent.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account`.","const":"account"},"name":{"type":"string","description":"Specifies the name of the account.","example":"acc-name"},"legal_name":{"type":["string","null"],"description":"Specifies the legal name of the account.","example":"acc-legal-name"},"registration_id":{"type":["string","null"],"description":"Specifies the registration ID. If specified, this field is checked for uniqueness.","example":"reg-id"},"external_ref":{"type":["string","null"],"description":"The unique attribute associated with the account. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`.","example":"ext-ref"}},"required":["type","name"],"title":"Account"},{"type":"object","properties":{"parent_id":{"type":["string","null"],"format":"uuid","description":"Specifies the ID of the parent account, this field cannot be changed after creation.","example":"96b1f750-55d3-4768-a3f8-adffba694a2c"}},"title":"WritableParentId"}]}},"required":["data"]},"examples":{"Create an account":{"value":{"data":{"type":"account","name":"acc-name","legal_name":"acc-legal-name","registration_id":"reg-id","external_ref":"ext-ref"}}},"Create a subaccount":{"value":{"data":{"type":"account","name":"acc-sub-name","legal_name":"acc-legal-name, ltd","registration_id":"reg-id","external_ref":"ext-ref","parent_id":"96b1f750-55d3-4768-a3f8-adffba694a2c"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account`.","const":"account"},"name":{"type":"string","description":"Specifies the name of the account.","example":"acc-name"},"legal_name":{"type":["string","null"],"description":"Specifies the legal name of the account.","example":"acc-legal-name"},"registration_id":{"type":["string","null"],"description":"Specifies the registration ID. If specified, this field is checked for uniqueness.","example":"reg-id"},"external_ref":{"type":["string","null"],"description":"The unique attribute associated with the account. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`.","example":"ext-ref"}},"required":["type","name"],"title":"Account"},{"type":"object","properties":{"parent_id":{"type":["string","null"],"format":"uuid","readOnly":true,"description":"Specifies the ID of the parent account.","example":"96b1f750-55d3-4768-a3f8-adffba694a2c"}},"title":"ReadOnlyParentId"},{"type":"object","properties":{"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this realm. For more information, see [The meta object](https://elasticpath.dev/docs/commerce-cloud/accounts/using-account-management-api/account-management-api-overview#the-meta-object) section.","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account_tags":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for an Account Tag.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"type":{"type":"string","const":"account_tag"}}}}},"description":"Tags associated with the account."},"ancestors":{"type":"array","items":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"type":{"type":"string","const":"account"}}}},"description":"All parent accounts in the hierarchy in sorted order (root first)."}},"parent":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"account"},"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"}}}}}}}}}],"title":"AccountResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"account membership with the given account id and account member id already exists"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unprocessable-entity":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"store id mismatch"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an account member

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an account member"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/account-members/{accountMemberID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

This endpoint can be used to update an account member.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountMemberID","in":"path","description":"The unique identifier of the account member that you want to update the flows of.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"account_member","description":"The type of the object."},"id":{"type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b95"}}}},"required":["data"]},"examples":{"Update an Account Member":{"value":{"data":{"type":"account_member"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"id":{"description":"The unique identifier for the account member.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"The type of the object that is returned.","type":"string","const":"account_member"},"name":{"description":"The name of the account member.","type":"string","example":"Ron Swanson"},"given_name":{"description":"The given name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Ron"},"middle_name":{"description":"The middle name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Ulysses"},"family_name":{"description":"The family name of the account member. This field is optional and not computed or extracted from the name field.","type":["string","null"],"example":"Swanson"},"email":{"description":"The email address of the account member.","type":"string","format":"email","example":"ron@swanson.com"}},"title":"AccountMember"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-members/908f7849-60da-4e4a-a3b1-51d4cbe3b953"}}}}}],"title":"AccountMemberResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-members/908f7849-60da-4e4a-a3b1-51d4cbe3b953"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an Account Membership

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Account Membership"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/accounts/{accountID}/account-memberships/{membershipID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can update and extend an account member details using [core flows](/docs/api/flows/flows#extend-an-existing-resource). However, you cannot update the `account_member_id` of an account member.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The unique identifier of the account that the account member is associated with.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"membershipID","in":"path","description":"The unique identifier of the account membership to update the details of the account member.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"account_member_id":{"type":"string","format":"uuid","description":"Specifies the unique identifier of the account member that the membership is associated with.","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"type":"string","const":"account_membership","description":"Specifies the type of the object. Set this value to `account_membership`."}},"title":"AccountMembership","required":["type","account_member_id"]}}},"examples":{"Update account membership":{"value":{"data":{"type":"account_membership","account_member_id":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"Represents the unique identifier for the account membership.","type":"string","format":"uuid","example":"24e939f6-178f-497b-9d64-5bf2b5a70a2e"},"type":{"description":"Represents the type of the object returned.","type":"string","const":"account_membership"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account_member":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"Specifies the ID of the account member.","type":"string","format":"uuid","example":"908f7849-60da-4e4a-a3b1-51d4cbe3b953"},"type":{"description":"Specifies the type of the account member.","type":"string","const":"account_member"}}}}}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/accounts/5b495058-9ffc-4b9b-810a-c9d43ffc6500/account-memberships/24e939f6-178f-497b-9d64-5bf2b5a70a2e"}}}},"title":"AccountMembershipResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/account-memberships/5ac48b3b-825d-43a3-9fcd-962230629d5e"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"account membership with the given account id and account member id already exists"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an Account

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Account"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/accounts/{accountID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update the information contained on an account.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account`.","const":"account"},"name":{"type":"string","description":"Specifies the name of the account.","example":"acc-name"},"legal_name":{"type":["string","null"],"description":"Specifies the legal name of the account.","example":"acc-legal-name"},"registration_id":{"type":["string","null"],"description":"Specifies the registration ID. If specified, this field is checked for uniqueness.","example":"reg-id"},"external_ref":{"type":["string","null"],"description":"The unique attribute associated with the account. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`.","example":"ext-ref"}},"required":["type","name"],"title":"Account"},{"type":"object","properties":{"parent_id":{"type":["string","null"],"format":"uuid","readOnly":true,"description":"Specifies the ID of the parent account.","example":"96b1f750-55d3-4768-a3f8-adffba694a2c"}},"title":"ReadOnlyParentId"}]}},"required":["data"]},"examples":{"Update an Account":{"value":{"data":{"type":"account","name":"acc-name","legal_name":"acc-legal-name","registration_id":"reg-id","external_ref":"ext-ref"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account`.","const":"account"},"name":{"type":"string","description":"Specifies the name of the account.","example":"acc-name"},"legal_name":{"type":["string","null"],"description":"Specifies the legal name of the account.","example":"acc-legal-name"},"registration_id":{"type":["string","null"],"description":"Specifies the registration ID. If specified, this field is checked for uniqueness.","example":"reg-id"},"external_ref":{"type":["string","null"],"description":"The unique attribute associated with the account. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`.","example":"ext-ref"}},"required":["type","name"],"title":"Account"},{"type":"object","properties":{"parent_id":{"type":["string","null"],"format":"uuid","readOnly":true,"description":"Specifies the ID of the parent account.","example":"96b1f750-55d3-4768-a3f8-adffba694a2c"}},"title":"ReadOnlyParentId"},{"type":"object","properties":{"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this realm. For more information, see [The meta object](https://elasticpath.dev/docs/commerce-cloud/accounts/using-account-management-api/account-management-api-overview#the-meta-object) section.","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"relationships":{"type":"object","properties":{"account_tags":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for an Account Tag.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"type":{"type":"string","const":"account_tag"}}}}},"description":"Tags associated with the account."},"ancestors":{"type":"array","items":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"type":{"type":"string","const":"account"}}}},"description":"All parent accounts in the hierarchy in sorted order (root first)."}},"parent":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"account"},"id":{"description":"The unique identifier for an Account.","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"}}}}}}}}}],"title":"AccountResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"detail":{"type":"string","example":"Validation failed: field 'Name' on the 'min' tag."},"status":{"type":"string","example":"400"},"title":{"type":"string","example":"Bad Request"}}}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"detail":{"type":"string","example":"account not found"},"status":{"type":"string","example":"404"},"title":{"type":"string","example":"Not Found"}}}}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"account membership with the given account id and account member id already exists"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update Account Authentication Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Account Authentication Settings"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings/account-authentication"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to update account authentication settings

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account_authentication_settings`.","const":"account_authentication_settings"},"enable_self_signup":{"description":"Set to `true` to enable self signup.","type":"boolean","example":true},"auto_create_account_for_account_members":{"description":"This will automatically create an account for each new account member, using the account member’s name as the account name.","type":"boolean","example":true},"account_member_self_management":{"description":"Whether a user with an [Account Management Authentication Token](/docs/api/accounts/post-v-2-account-members-tokens) can update their own account member details. By default, this is `disabled`. Set to `update_only` if you want the user to be able to update their own account member details (e.g., name, email, and if applicable their username and password). The user can update their own account member details by updating their [User Authentication Info](/docs/authentication/single-sign-on/user-authentication-info-api/update-a-user-authentication-info) using the `account_member_id` retrieved from the `meta` in the response of [Generating an Account Management Authentication Token](/docs/api/accounts/post-v-2-account-members-tokens) as the `id` and find the authentication credentials to update by calling the [Get All User Authentication Password Profile Info](/docs/authentication/single-sign-on/user-authentication-password-profiles-api/get-all-user-authentication-password-profile-info) endpoint.","type":"string","default":"disabled","enum":["disabled","update_only"]},"account_management_authentication_token_timeout_secs":{"description":"The expiry time for Account Management Authentication Token in seconds. If you want to implement idle timout for you application, see [Implementing Idle Timeout](/guides/How-To/Accounts/implement-idle-timeout)","type":"integer","default":86400,"example":86400}},"title":"AccountAuthenticationSettings"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account_authentication_settings`.","const":"account_authentication_settings"},"enable_self_signup":{"description":"Set to `true` to enable self signup.","type":"boolean","example":true},"auto_create_account_for_account_members":{"description":"This will automatically create an account for each new account member, using the account member’s name as the account name.","type":"boolean","example":true},"account_member_self_management":{"description":"Whether a user with an [Account Management Authentication Token](/docs/api/accounts/post-v-2-account-members-tokens) can update their own account member details. By default, this is `disabled`. Set to `update_only` if you want the user to be able to update their own account member details (e.g., name, email, and if applicable their username and password). The user can update their own account member details by updating their [User Authentication Info](/docs/authentication/single-sign-on/user-authentication-info-api/update-a-user-authentication-info) using the `account_member_id` retrieved from the `meta` in the response of [Generating an Account Management Authentication Token](/docs/api/accounts/post-v-2-account-members-tokens) as the `id` and find the authentication credentials to update by calling the [Get All User Authentication Password Profile Info](/docs/authentication/single-sign-on/user-authentication-password-profiles-api/get-all-user-authentication-password-profile-info) endpoint.","type":"string","default":"disabled","enum":["disabled","update_only"]},"account_management_authentication_token_timeout_secs":{"description":"The expiry time for Account Management Authentication Token in seconds. If you want to implement idle timout for you application, see [Implementing Idle Timeout](/guides/How-To/Accounts/implement-idle-timeout)","type":"integer","default":86400,"example":86400}},"title":"AccountAuthenticationSettings"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"relationships":{"type":"object","properties":{"authentication_realm":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"The ID of the authentication realm entity.","type":"string","format":"uuid","example":"3418c54e-d768-42c1-a9db-d7afd2a18452"},"type":{"description":"The type of the authentication realm entity.","type":"string","const":"authentication_realm"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/authentication-realms/3418c54e-d768-42c1-a9db-d7afd2a18452"}}}}}}}}},"meta":{"type":"object","properties":{"client_id":{"description":"The client ID to be used in Single Sign On authentication flows for accounts.","type":"string","example":"account-management"}}}}}]},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account_authentication_settings"}}}},"title":"AccountAuthenticationSettingsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unprocessable-entity":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"store id mismatch"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update Account Membership Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Account Membership Settings"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings/account-membership"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to update account membership settings.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account_membership_setting`.","example":"account_membership_setting","enum":["account_membership_setting"]},"membership_limit":{"type":"integer","description":"The number of accounts an account member can be associated with. You can set this value to any number up to 10,000.","example":100}}}},"title":"AccountMembershipSettings"},"examples":{"Update account membership limit":{"value":{"data":{"type":"account_membership_setting","membership_limit":1000}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `account_membership_setting`.","example":"account_membership_setting","enum":["account_membership_setting"]},"membership_limit":{"type":"integer","description":"The number of accounts an account member can be associated with. You can set this value to any number up to 10,000.","example":100}}}},"title":"AccountMembershipSettings"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Remove Account Tags

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Remove Account Tags"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/accounts/{accountID}/relationships/account-tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Remove Account Tags from an Account. Please note that after removing a tag from an account, the account member token should be regenerated to reflect the updated status, allowing other services to react accordingly. See [Account Management Authentication Token](/docs/api/accounts/post-v-2-account-members-tokens).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for the related Account Tag.","type":"string","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"description":"Specifies the type of the resource object.","type":"string","const":"account_tag"}},"title":"AccountTagsRelationshipIdentifier"}}},"title":"RemoveAccountTagsOnAccount"},"examples":{"Remove Example":{"summary":"Remove an Account Tag","value":{"data":[{"type":"account_tag","id":"030693ce-39ad-4f4c-9941-d2d596478e94"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for the related Account Tag.","type":"string","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"description":"Specifies the type of the resource object.","type":"string","const":"account_tag"}},"title":"AccountTagsRelationshipIdentifier"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/relationships/account-tags"}}}},"title":"AccountTagsRelationshipResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an Account Tag

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Account Tag"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/account-tags/{tag_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update an Account Tag

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"tag_id","description":"The ID of the Account Tag.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Specifies the type of the resource object, use `account_tag` for Account Tags.","type":"string","const":"account_tag"},"name":{"type":"string","description":"Specifies the name of the account tag.","example":"account-name-tag"},"description":{"type":"string","description":"Describes the account tag."}},"title":"AccountTag"}},"required":["data"]},"examples":{"Update Example":{"summary":"Update an Account Tag","value":{"data":{"type":"account_tag","name":"Account Name","description":"Account Description"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"description":"Specifies the type of the resource object, use `account_tag` for Account Tags.","type":"string","const":"account_tag"},"name":{"type":"string","description":"Specifies the name of the account tag.","example":"account-name-tag"},"description":{"type":"string","description":"Describes the account tag."}},"title":"AccountTag"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/account-tags/deb6b25f-8451-4211-9a22-95610333df23"}}}}}],"title":"AccountTagResponse"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"account not found"}]}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"account membership with the given account id and account member id already exists"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Account Addresses

The API to organize account addresses.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Addresses Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/addresses/AccountAddresses.OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Addresses Introduction"}
>
</Heading>

The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.

You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"BearerToken"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Delete an Account Address

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an Account Address"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/accounts/{accountID}/addresses/{addressID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete an address for an Account.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account that contains the address to delete.","required":true,"schema":{"type":"string"}},{"name":"addressID","in":"path","description":"The ID of the address to delete.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"account not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Account Address

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Account Address"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/accounts/{accountID}/addresses/{addressID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a specific address for an Account.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to retrieve.","required":true,"schema":{"type":"string"}},{"name":"addressID","in":"path","description":"The ID of the address you want to retrieve.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `address`.","const":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"description":"The ID of the account.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"account"}}}}}}}],"title":"AccountAddressResponse","type":"object"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"account not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Account Addresses

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Account Addresses"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/accounts/{accountID}/addresses"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all addresses for an Account.

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

### Filtering

The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) addresses:

| Attribute      | Operators                       | Example                               |
|----------------|---------------------------------|---------------------------------------|
| `name`         | `eq`,`in`,`like`,`ilike`,`text` | `ilike(name,"*home*")`                |
| `first_name`   | `eq`,`in`,`like`,`ilike`,`text` | `ilike(first_name,"Ron*")`            |
| `last_name`    | `eq`,`in`,`like`,`ilike`,`text` | `ilike(last_name,"*swan*")`           |
| `phone_number` | `eq`,`in`,`like`,`ilike`,`text` | `ilike(phone_number,"*555*")`         |
| `company_name` | `eq`,`in`,`like`,`ilike`,`text` | `ilike(company_name,"*enterprises*")` |
| `instructions` | `eq`,`in`,`like`,`ilike`,`text` | `text(instructions,"behind bin")`     |
| `line_1`       | `eq`,`in`,`like`,`ilike`,`text` | `ilike(line_1,"*Sunny Street*")`      |
| `line_2`       | `eq`,`in`,`like`,`ilike`,`text` | `ilike(line_2,"*Unit*")`              |
| `city`         | `eq`,`in`,`like`,`ilike`,`text` | `eq(city,"Sunny Town")`               |
| `county`       | `eq`,`in`,`like`,`ilike`,`text` | `eq(county,"Sunnyville")`             |
| `region`       | `eq`,`in`,`like`,`ilike`,`text` | `eq(region,"California")`             |
| `postcode`     | `eq`,`in`,`like`,`ilike`,`text` | `eq(postcode,"SU33 1YY")`             |
| `country`      | `eq`,`in`,`like`,`ilike`,`text` | `eq(country,"GB")`                    |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to retrieve.","required":true,"schema":{"type":"string"}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. If not specified, defaults to the `page_length` setting from the Settings API.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"page[total_method]","in":"query","description":"The method used to calculate the total count. `lower_bound` limits expensive count operations, `observed` uses a lightweight +1 fetch strategy that will indicate if there is a next page.","required":false,"schema":{"type":"string","enum":["lower_bound","observed"],"default":"lower_bound"}},{"name":"filter","in":"query","description":"Filter addresses using a simple query language.","required":false,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `address`.","const":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"description":"The ID of the account.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"account"}}}}}}}],"title":"AccountAddressResponse"}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page.","example":25},"offset":{"type":"integer","description":"The current offset by number of records.","example":0},"current":{"type":"integer","description":"The current page number.","example":1},"total":{"type":"integer","description":"The total number of pages.","example":3}},"title":"PaginationPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results.","example":75},"total_method":{"type":"string","description":"The method used to calculate the total. `exact` means the precise count is known, `lower_bound` means the count is at least this value, `observed` means the count is estimated from observations.","enum":["exact","lower_bound","observed"],"example":"exact"}},"title":"PaginationResults"}},"title":"PaginationMeta"},"links":{"type":"object","properties":{"current":{"type":"string","description":"The URL to the current page.","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=0&page[limit]=25"},"first":{"type":"string","description":"The URL to the first page.","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=0&page[limit]=25"},"last":{"type":["string","null"],"description":"The URL to the last page. May be null if the total is unknown.","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=50&page[limit]=25"},"next":{"type":["string","null"],"description":"The URL to the next page. Null if on the last page.","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=25&page[limit]=25"},"prev":{"type":["string","null"],"description":"The URL to the previous page. Null if on the first page.","example":null}},"title":"PaginationLinks"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"status":400,"title":"Bad Request","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"account not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create an Account Address

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Account Address"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/accounts/{accountID}/addresses"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create an address for an Account.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to create an address for.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `address`.","const":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `address`.","const":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"description":"The ID of the account.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"account"}}}}}}}],"title":"AccountAddressResponse"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `address`.","const":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"description":"The ID of the account.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"account"}}}}}}}],"title":"AccountAddressResponse"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"status":400,"title":"Bad Request","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"account not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an Account Address

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Account Address"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/accounts/{accountID}/addresses/{addressID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update an address for an Account.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"accountID","in":"path","description":"The ID of the account you want to create an address for.","required":true,"schema":{"type":"string"}},{"name":"addressID","in":"path","description":"The ID of the address you want to update.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `address`.","const":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `address`.","const":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/accounts/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"description":"The ID of the account.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"account"}}}}}}}],"title":"AccountAddressResponse","type":"object"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"status":400,"title":"Bad Request","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"account not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Application Keys Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/application-keys/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Application Keys Introduction"}
>
</Heading>

Application keys are used to directly manage access to Organizations and stores. These keys are identified based on their names, and are not associated with a user.

You can use application keys to generate `client_credentials` and `implicit tokens`. Unlike [User Credentials](/docs/authentication/security#user-credentials), Application keys are still valid even after a team member is removed from a store or organization.

Each organization and store has a specific [rate limit](/guides/Getting-Started/rate-limits). You can fine-tune the performance and availability of your applications that are integrated with our platform by reserving a rate limit for each Application Key. Reserved rate limits ensures that applications using a token generated from that key can make at least that many requests per second.

## Scenarios

For example, consider the following two scenarios for using reserved rate limits:

  - Scenario 1: Suppose you use a key for your store front. You can reduce the risk of customers experiencing throttling while shopping by reserving a majority of your store's rate limit for that store front to ensure a smooth shopping experience.

  - Scenario 2: If you have a key for the store front but you also need to support several backend processes syncing data across systems, you can reserve a part of your store's rate limit to your store front key. This ensures that the backend process doesn't slow down the store front. Additionally, you can also reserve a rate limit for the key that is associated with most critical backend process.

  It is important to note that the sum of the reserved value for all keys in your store or organization cannot exceed the total allowed requests per second for that store or organization. For example, suppose a store has a rate limit of 100 requests per second, and there is already a key that has a reserved limit of 80 requests per second. If you try to create a new key with reserved rate limit of 21 requests per second, the request will fail. However, if you reserve only 20 requests per second, it will succeed as it doesn't exceed the store's rate limit.

  Keys without a reserved rate limits share from the same pool. If the total reserved rate limit across keys reaches the total rate limit for your store or organization, there will be nothing left in the unreserved, shared pool. Keys without a reserved rate limit will experience throttling when they attempt to make requests. Keys with a reserved rate limit can also use this shared pool.

  Adjustments made to the reserved rate limit may take up to one hour to become effective.

  The following table describes the management of application keys for organizations and stores.

  | Organizations | Stores |
  | --------------- | -------- |
  | Application keys are granted the same permissions as Org Admins. | Application keys are granted the same permissions as Store Admins. |
  | Org Admins can view and manage the list of application keys in their organization and all stores belonging to that organization. | Store Admins can view and manage the list of application keys within the store. |
  | Application keys can be used to manage access to an organization and all stores in the organization. | Application keys can be used to manage access to a store. |

## Best Practices for Application Keys

- Assign a descriptive name for the application key associated with its purpose.
- Create a unique application key each each distinct type of interactions, such as storefront and back-end interactions.
- Do not embed API keys directly in your code.
- Do not store API keys in files within your application's source tree.
- Regularly review your application keys and delete any that are no longer in use.
- Assign a reserved rate limit for your critical application keys.
- Do not fully reserve the rate limit for your store or organizations across all keys. Instead, reserve rate limits thoughtfully to ensure that keys without a reserved rate limit can draw from a shared pool when needed.

  To create your application key, see [Creating an Application Key](/docs/commerce-manager/application-keys/application-keys-cm).

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Application Keys

You can use application keys to generate `client_credentials` and `implicit` tokens.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Create an Application Key

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Application Key"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/application-keys"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create an Application Key

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","name"],"properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `application_key` for application keys.","const":"application_key"},"name":{"type":"string","description":"Specifies the name of the application key.","minLength":1,"maxLength":255},"reserved_rate_limit":{"type":"integer","description":"Indicates the reserved rate limit for an application key. For more information, see [Application Keys Overview](/docs/api/application-keys/application-keys-introduction).","minimum":0}}}}},"examples":{"Create Example":{"summary":"Create an Application Key","value":{"data":{"type":"application_key","name":"Storefront-Key","reserved_rate_limit":0}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"An Application Key","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Application Key.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, always `application_key` for Application Keys.","const":"application_key"},"name":{"type":"string","description":"Specifies the name of this Application Key.","minLength":1,"maxLength":255},"reserved_rate_limit":{"type":"integer","description":"Indicates the reserved rate limit for an application key. For more information, see [Application Keys Overview](/docs/api/application-keys/application-keys-introduction).","minimum":0},"client_id":{"type":"string","description":"Represents the unique `client_id`.","example":"Z2dDp1f1Tg30p2C6ZVit7W1AKUtVhMVSTAPOIK4adA"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"},"last_used_at":{"type":["string","null"],"description":"Specifies the approximate last used date of the Application Key. A `null` value indicates that the key has not been used.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"ApplicationKey"},{"type":"object","properties":{"client_secret":{"type":"string","description":"Represents the unique `client_secret`.","example":"jN8qLHneOn8C1rv0r3J3XZK1cRiZG3rajcLi9X1cZZ"}}}]},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Application Key.","example":"/v2/application-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Exceed Rate Limit":{"summary":"Requested limit exceeds maximum","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"Requested reserved rate limit will exceed the maximum.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Delete an Application Key

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an Application Key"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/application-keys/{application-key-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete an Application Key

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"application-key-id","description":"The unique identifier of the Application Key.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get an Application Key

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Application Key"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/application-keys/{application-key-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get an Application Key

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"application-key-id","description":"The unique identifier of the Application Key.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"An Application Key","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Application Key.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, always `application_key` for Application Keys.","const":"application_key"},"name":{"type":"string","description":"Specifies the name of this Application Key.","minLength":1,"maxLength":255},"reserved_rate_limit":{"type":"integer","description":"Indicates the reserved rate limit for an application key. For more information, see [Application Keys Overview](/docs/api/application-keys/application-keys-introduction).","minimum":0},"client_id":{"type":"string","description":"Represents the unique `client_id`.","example":"Z2dDp1f1Tg30p2C6ZVit7W1AKUtVhMVSTAPOIK4adA"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"},"last_used_at":{"type":["string","null"],"description":"Specifies the approximate last used date of the Application Key. A `null` value indicates that the key has not been used.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"ApplicationKey"},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Application Key.","example":"/v2/application-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## List Application Keys

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Application Keys"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/application-keys"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of Application Keys

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":0}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List of Application Keys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Application Key.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, always `application_key` for Application Keys.","const":"application_key"},"name":{"type":"string","description":"Specifies the name of this Application Key.","minLength":1,"maxLength":255},"reserved_rate_limit":{"type":"integer","description":"Indicates the reserved rate limit for an application key. For more information, see [Application Keys Overview](/docs/api/application-keys/application-keys-introduction).","minimum":0},"client_id":{"type":"string","description":"Represents the unique `client_id`.","example":"Z2dDp1f1Tg30p2C6ZVit7W1AKUtVhMVSTAPOIK4adA"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"},"last_used_at":{"type":["string","null"],"description":"Specifies the approximate last used date of the Application Key. A `null` value indicates that the key has not been used.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"ApplicationKey"}},"meta":{"type":"object","properties":{"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results for the entire collection."}}},"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records for all pages.","example":100},"offset":{"type":"integer","description":"The current offset by number of pages.","example":0},"current":{"type":"integer","description":"The current number of pages.","example":1},"total":{"type":"integer","description":"The total number of pages.","example":1}}},"total_reserved_rate_limit":{"type":"integer","description":"Sum of rate limit reserved for all application keys.","example":100}},"title":"ListMeta"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","example":"/v2/application-keys?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"first":{"description":"Always the first page.","example":"/v2/application-keys?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"last":{"description":"Always `null` if there is only one page.","example":"/v2/application-keys?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"next":{"description":"Always `null` if there is only one page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"},"prev":{"description":"Always `null` if on the first page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"}},"title":"PaginationLinks"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Update an Application Key

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Application Key"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/application-keys/{application-key-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update an Application Key

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"application-key-id","description":"The unique identifier of the Application Key.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `application_key` for application keys.","const":"application_key"},"name":{"type":"string","description":"Specifies the name of the application key.","minLength":1,"maxLength":255},"reserved_rate_limit":{"type":"integer","description":"Indicates the reserved rate limit for an application key. For more information, see [Application Keys Overview](/docs/api/application-keys/application-keys-introduction).","minimum":0}}}}},"examples":{"Update Example":{"summary":"Update a Application Key","value":{"data":{"type":"application_key","name":"Batch-Processing","reserved_rate_limit":10}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"An Application Key","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Application Key.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, always `application_key` for Application Keys.","const":"application_key"},"name":{"type":"string","description":"Specifies the name of this Application Key.","minLength":1,"maxLength":255},"reserved_rate_limit":{"type":"integer","description":"Indicates the reserved rate limit for an application key. For more information, see [Application Keys Overview](/docs/api/application-keys/application-keys-introduction).","minimum":0},"client_id":{"type":"string","description":"Represents the unique `client_id`.","example":"Z2dDp1f1Tg30p2C6ZVit7W1AKUtVhMVSTAPOIK4adA"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"},"last_used_at":{"type":["string","null"],"description":"Specifies the approximate last used date of the Application Key. A `null` value indicates that the key has not been used.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"ApplicationKey"},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Application Key.","example":"/v2/application-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Exceed Rate Limit":{"summary":"Requested limit exceeds maximum","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"Requested reserved rate limit will exceed the maximum.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Authentication

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/authentication/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Authentication"}
>
</Heading>

All API endpoints require authentication. To authenticate your request, you will need to provide an access token. Access tokens are generated via an [authentication API endpoint](/docs/api/authentication/create-an-access-token).

After creating an access token, you can authenticate your request by sending the access token in the `Authorization` header of your request:

```json
Authorization: Bearer 212LJ3k0i2382364HIUEjfeJB98yvH
```

:::note
Read our [Quick Start guide](/guides/Getting-Started/your-first-api-request) on how to make your first API request.
:::

Access tokens expire after 1 hour. You will have to generate a new one. If you’re using our [JavaScript SDK](https://github.com/elasticpath/js-sdk), this is automatically handled for you.

## Client Credentials vs. Implicit Use Case Scenarios

There are two authentication methods, `client_credentials` and `implicit`. The `implicit` authentication will generate an access token that has more limited access, restricting access to mostly read-only, whereas the access token from `client_credentials` has full read and write access. Typically, you would use the `implicit` authentication method for client-side browser based applications (i.e. frontend), and `client_credentials` for all administrative tasks (`CRUD`) you need to perform at the backend.

## Shopper Authentication

An implicit access token is often used alongside an Account Management authentication token or a Customer token to access resources restricted to a shopper.

### Account Authentication

Account Management authentication tokens are available for anyone using the [Account Management APIs](/docs/api/accounts/account-management-introduction).

For each element in the list returned by the account member authentication API, a `token` value is returned. In order for a shopper to authenticate as the account, this value should be set as the `EP-Account-Management-Authentication-Token` header when calling Commerce. This header grants access to additional resources associated with the account, such as [carts](/docs/api/carts/account-cart-associations), [orders](/docs/api/carts/get-customer-orders), [catalogs with associated rules](/docs/api/pxm/catalog/rules), and [addresses](/docs/api/addresses/addresses-introduction).

The set of permissions available to a shopper using an Account Management Authentication token is documented in [Permissions](/docs/authentication/tokens/permissions#implicit-account-management-authentication-token).

For more information on implementing account management authentication tokens, see [Account Management Authentication Tokens](/docs/api/accounts/post-v-2-account-members-tokens).

### Customer Authentication

Customer tokens are available for anyone using the [Customer APIs](/docs/customer-management/customers).

A customer token provides access to the records of the customer. Use single sign-on or the email address and password of the customer to retrieve the [customer tokens](/docs/customer-management/customer-management-api/customer-tokens). The customer token should be set as the `X-Moltin-Customer-Token` header to access the following APIs:

- [Get a Customer](/docs/customer-management/customer-management-api/get-a-customer)
- [Update a Customer](/docs/customer-management/customer-management-api/update-a-customer)
- [Get Customer Addresses](/docs/api/customer-addresses/get-v-2-customer-addresses)
- [Get an Address](/docs/api/customer-addresses/get-v-2-customer-addresses)
- [Create an Address](/docs/api/addresses/get-v-2-account-address)
- [Update an Address](/docs/api/addresses/put-v-2-account-address)
- [Get all Orders](/docs/api/carts/get-customer-orders)
- [Get an Order](/docs/api/carts/get-an-order)
- [Get Customer Carts](/docs/api/carts/create-a-cart)
- [Create an Association between a Customer and a Cart](/docs/api/carts/create-customer-cart-association)
- [Delete an Association Between a Customer and a Cart](/docs/api/carts/delete-customer-cart-association)
- [Add Promotion to Cart](/docs/api/carts/manage-carts#add-promotion-to-cart)

For more information on implementing customer tokens, see [Customer Tokens](/docs/customer-management/customer-management-api/customer-tokens).

## Organization

To help with managing stores within an organization, the access token generated for the organization can be used to authenticate requests for any store within the organization.
To make a request to a store within the organization:
1. Set the `EP-Org-ID` header with the organization ID
2. Set the `EP-Store-ID` header with the store ID

For example, to get all the application keys for a store with ID `9adcc2d3-6a39-4057-bbc1-b036f1d6c735` that is part of the organization with ID `afb3dd03-1c89-4ff8-8611-cf759b15827f`:
```bash
curl -X GET 'https://useast.api.elasticpath.com/v2/application-keys' \
-H 'Authorization: Bearer d5525335fedf1b20f081f641d8d32980ec553b5c' \
-H 'EP-Org-ID: afb3dd03-1c89-4ff8-8611-cf759b15827f' \
-H 'EP-Store-ID: 9adcc2d3-6a39-4057-bbc1-b036f1d6c735'
```

## Authenticating for Use on the Documentation site

In order to perform any of the API requests directly on the documentation site, you will need to authenticate to get an access token. After the first request, any subsequent request will continue to use the same access token.

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Create an Access Token

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Access Token"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/oauth/access_token"}
  context={"endpoint"}
>
  
</MethodEndpoint>

### Client Credentials

A `client_credentials` token is used when the credentials are not publicly exposed, usually a server-side language such as PHP or Node.js. This type of authentication enables `CRUD` access to all resources.

`client_id` and `client_secret` are created and managed via [Application Keys](/docs/api/application-keys/create-an-application-key).

To see the access granted by a `client_credentials` token, refer to [Permissions](/docs/authentication/tokens/permissions).

### Implicit

An `implicit` token is typically used for situations where you are requesting data on the client side and you are exposing your public key. When authenticated implicitly, you can only fetch (`GET`) data with live status (products, categories, brands, etc).

The `implicit` token is most appropriate for use inside client-side applications, such as JavaScript.

:::caution
An `implicit` token can be thought of as a **Read only** token.
:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id"],"properties":{"grant_type":{"type":"string","description":"The grant type.","enum":["client_credentials","implicit"]},"client_id":{"type":"string","description":"Your `client_id`"},"client_secret":{"type":"string","description":"Your `client_secret`. Only required for client credentials."}}},"examples":{"Create Example":{"summary":"Create an Access Token using Client Credentials","value":{"grant_type":"client_credentials","client_id":"jJBrLb0q1Q7bZ5GiGttD5T1471b0IeXAVgNyOlw19q","client_secret":"mzr6gnvdQODSgT3mSxxWIv3y8pAp8cUzDELXa3g4fB"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Access Token","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","description":"The access token you use to authenticate requests to the API."},"token_type":{"type":"string","description":"Right now this is only `Bearer`."},"identifier":{"type":"string","description":"The type of token requested. This can be a `client_credentials` or `implicit`."},"expires_in":{"type":"integer","description":"The duration in seconds after which the token expires."},"expires":{"type":"integer","description":"The epoch time that this token expires at."}}},"examples":{"Client Credentials":{"summary":"Access token from Client Credentials","value":{"access_token":"xa3521ca621113e44eeed9232fa3e54571cb08bc","token_type":"Bearer","expires_in":3600,"expires":1524486008,"identifier":"client_credentials"}},"Implicit":{"summary":"Access token from Implicit","value":{"access_token":"xa3521ca621113e44eeed9232fa3e54571cb08bc","token_type":"Bearer","expires_in":3600,"expires":1524486008,"identifier":"implicit"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"bad-request-error":{"summary":"Bad Request","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required\"\n    }\n  ]\n}\n"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"unauthorized-error":{"summary":"Unauthorized","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Unauthorized\",\n      \"status\": \"401\",\n      \"detail\": \"Unauthorized\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Account Cart Associations

You can create associations between an account and one or more carts. After cart associations exist for an account, those carts are accessible across any device. You can delete associations as required.

There are two ways to access the cart: with an [Account Management Authentication Tokens](/docs/api/accounts/post-v-2-account-members-tokens) and without one.

### With an `Account Management Authentication` token

These endpoints are for users who authenticated implicitly and require an Account Management Authentication token in the header to access the account cart associations APIs. For more information, see the [Account Token](/docs/api/accounts/post-v-2-account-members-tokens) documentation.

#### Cart creation

Shoppers create carts and can use any of the carts that they created to check out an order.

:::note

You can create a cart id, name, and description for the cart. The cart requires a name. Ensure that the string length is greater than or equal to one. Use any symbol in the name and description. For cart id, ensure that you follow the guidelines for safe characters. For more information about cart id naming requirements, see [Safe Characters](/guides/Getting-Started/safe-characters).

:::

### Without an `Account Management Authentication` token

These endpoints are for users who use the Client Credentials Token and do not require an account management authentication token in the header to access the account cart associations APIs. For more information, see the [Authentication](/docs/authentication/security) documentation.

This user acts as a system administrator and can call any account cart association operations for any account and cart.

### Error Codes

You might encounter the following response codes, depending on the scenario:

* `400` - `The type does not exist or is not listed as account` - Ensure that the type is `account` and is present.

* `403` - `Cannot associate more than one account`.

* `403` - `Account does not have the required permissions to fulfill this request`.

* `403` - `Invalid json payload` - Check JSON input. The request body must be an array `[]`. If the request body is an object, the error is generated.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Add Custom Discount To Cart Item

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Add Custom Discount To Cart Item"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/custom-discounts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to add a custom discount to cart item. Custom discounts cannot be combined with Elastic Path promotions. If the cart already contains Elastic Path promotions, remove them before adding custom discounts.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"Specifies the ID for the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"Specifies the unique identifier for the cart item.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successful request","headers":{},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"data":{"type":"array","items":{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}}},"title":"CartsCustomDiscountsCollectionResponse"},{"type":"object","properties":{"data":{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"title":"CartsCustomDiscountsEntityResponse"}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Required field missing","value":{"errors":[{"detail":"Custom discounts not enabled for this cart","status":400,"title":"Bad Request"}]}}}}}},"422":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Discount Limit Reached","value":{"errors":[{"detail":"Custom discount limit reached for this cart item","status":422,"title":"Limit Reached"}]}},"cart-contains-elastic-path-promotions":{"summary":"Cart contains Elastic Path promotions","value":{"errors":[{"detail":"Custom discounts cannot be combined with Elastic Path promotions. Remove all Elastic Path promotions from the cart before adding custom discounts.","status":422,"title":"Cart contains Elastic Path promotions"}]}}}}}}}}
>
  
</StatusCodes>

---

## Add Tax Item to Bundle Component

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Add Tax Item to Bundle Component"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/components/{productID}/taxes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to add a tax item to a specific bundle component (component product) within a cart item.

:::note

There is a soft limit of 5 unique tax items per component product at any one time.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"The unique identifier of the cart item.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"productID","in":"path","description":"The unique identifier of the component product within the bundle.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"rateTaxItemComponent":{"summary":"Add a rate-based tax item to a bundle component","value":{"data":{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2}}},"amountTaxItemComponent":{"summary":"Add an amount-based tax item to a bundle component","value":{"data":{"type":"tax_item","code":"PST","jurisdiction":"CA-BC","name":"Provincial Sales Tax","amount":250}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"componentRateTaxItem":{"summary":"Rate-based tax item on bundle component","value":{"data":{"id":"4f4e6d37-8c8c-4a1a-b8a3-6cd2efab12de","type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Add Tax Item to Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Add Tax Item to Cart"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/taxes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to add a tax item to a cart.

:::note

There is a soft limit of 5 unique tax items per cart item at any one time.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"The unique identifier of the cart item.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"rateTaxItem":{"summary":"Add a rate-based tax item","value":{"data":{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2}}},"amountTaxItem":{"summary":"Add an amount-based tax item","value":{"data":{"type":"tax_item","code":"GST","jurisdiction":"AU","name":"Goods and Services Tax","amount":1000}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"rateTaxItem":{"summary":"Rate-based tax item","value":{"data":{"id":"662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9","type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2}}}}}}},"201":{"description":"Created","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"amountTaxItem":{"summary":"Amount-based tax item","value":{"data":{"id":"3f3b5e26-7e7e-4d2d-a3a7-5e9b1f72fabc","type":"tax_item","code":"GST","jurisdiction":"AU","name":"Goods and Services Tax","amount":1000}}}}}}},"422":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Anonymize Orders

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Anonymize Orders"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/orders/anonymize"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can anonymize an order when it is fulfilled, canceled, or fully refunded.

When anonymization is successful, Personal Identifiable Information such as customer details, `shipping_address`, and `billing_address` are replaced with *.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"OrdersAnonymizeRequest","type":"object","properties":{"data":{"title":"OrdersAnonymizeData","type":"object","properties":{"order_ids":{"description":"The unique identifiers of the orders to be anonymized. You can anonymize multiple orders at the same time.","type":"array","items":{"type":"string"},"examples":[["{{orderID}}"]]}}}}},{"examples":[{"data":{"order_ids":["{{orderID}}"]}}]}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"order_ids":["{{orderID}}"]}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"OrderResponse","type":"object","properties":{"type":{"description":"Specifies the type of object being returned. You must use `order`.","type":"string","const":"order"},"order_number":{"description":"Specifies a user-managed, optional field used as an alternative to the existing `order_id`. If provided, the order-number will be sent to Authorize.net instead of the `order_id`, and will appear as the invoice number in Authorize.net transactions.","type":"string","examples":[1234]},"external_ref":{"description":"An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","examples":["e-123456789"]},"id":{"description":"Specifies the unique identifier of the order.","type":"string","format":"uuid","readOnly":true,"examples":["aa854b8f-5930-476d-951a-e9b9cfbdefb1"]},"status":{"description":"Specifies the status of the order, such as `incomplete`, `complete`, `processing`, or `cancelled`.","type":"string","enum":["complete","incomplete","cancelled","processing"]},"payment":{"description":"Specifies the status of the payment, such as `unpaid`, `authorized`, `paid`, or `refunded`.","type":"string","enum":["authorized","paid","unpaid","refunded","partially_paid","partially_authorized"]},"shipping":{"description":"Specifies the status of the shipment, such as `fulfilled` or `unfulfilled`.","type":"string","enum":["unfulfilled","fulfilled"]},"anonymized":{"description":"Specifies if the order is anonymized.","type":"boolean","examples":[false]},"payment_intent_id":{"description":"Stripe Payment Intent ID.  Please see Stripe's Payment Intent [documentation](https://docs.stripe.com/api/payment_intents) for more information on Payment Intents.","type":"string","examples":["pi_3MtwBwLkdIwHu7ix28a3tqPa"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"links":{"type":"object"},"meta":{"title":"OrderMeta","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this order was created.","type":"string"},"updated_at":{"description":"The date this order was last updated.","type":"string"},"fully_paid_at":{"description":"The date this order was fully paid. Only present for orders with payment status 'paid'.","type":"string"}},"title":"OrderTimestamps"},"display_price":{"description":"Order pricing information including amounts, tax, discounts, and payment details.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}}},"is_manual":{"description":"Specifies if the order was created manually.","type":"boolean"}}},"billing_address":{"title":"BillingAddress","description":"Billing address information. You must specify at least one of region (state/province) or county.\n","anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}],"examples":[{"first_name":"John","last_name":"Doe","company_name":"John Doe Enterprises","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB"}]},"contact":{"title":"Contact","type":"object","properties":{"email":{"description":"The email address of the contact.","type":"string","examples":["johndoe@email.com"]},"name":{"description":"The name of the contact.","type":"string","examples":["John Doe"]}}},"customer":{"title":"Customer","type":"object","properties":{"name":{"description":"The name of the customer.","type":"string","examples":["John Doe"]},"email":{"description":"The email address of the customer.","type":"string","format":"email","examples":["john.doe@example.com"]},"id":{"description":"The unique identifier of the customer.","type":"string","format":"uuid","examples":["e5a0d684-a4af-4919-a348-f66b0b4955e0"]}}},"shipping_address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"relationships":{"type":"object","properties":{"items":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"customer":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account_member":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"store":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}}}},"required":["data"],"title":"OrdersListResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"detail":"Order has status: order:incomplete, payment:unpaid, shipping:unfulfilled; only fulfilled or refunded or cancelled orders may be anonymized","status":422,"title":"Could not anonymize orders","meta":{"order_id":"496c29a1-6e7a-4ab6-a4e7-d1ec9a08b85e"}}]}}}}}}
>
  
</StatusCodes>

---

## Bulk Add Custom Discounts to Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Bulk Add Custom Discounts to Cart"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/custom-discounts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The default value for custom discounts on both the cart and cart items is set to 5 if this parameter is not configured in the store. To verify the custom discount limit value, call [Get all settings](/docs/api/settings/get-v-2-settings) endpoint.

To increase the custom discount value, contact [Elastic Path Support team](https://support.elasticpath.com/hc/en-us).

Custom discounts cannot be combined with Elastic Path promotions. If the cart already contains Elastic Path promotions, remove them before adding custom discounts.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"Specifies the system generated ID for the cart that the shopper created.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"title":"CartsBulkCustomDiscounts","type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}},{"title":"CartItemBulkCustomDiscountObject","type":"object","allOf":[{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}},{"title":"CustomDiscountRelationshipsCartItemRequest","type":"object","properties":{"relationships":{"type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","required":["type","id"],"properties":{"type":{"description":"Specifies the type of item. For example, `custom_item` or `cart_item`.","type":"string","examples":["cart_item"]},"id":{"description":"Specifies the unique identifier of the `cart_item` or `custom_item` in the cart.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}}}}]}]}},"options":{"title":"Add All Or Nothing Options Object","type":"object","properties":{"add_all_or_nothing":{"description":"When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`.","type":"boolean","examples":[false]}}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"","headers":{},"content":{"application/json":{"schema":{"oneOf":[{"title":"CartsBulkCustomDiscountsResponse","type":"object","properties":{"data":{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}},"errors":{"type":"array","description":"Array of validation or processing errors","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}}},{"title":"CartsBulkCustomDiscountsCollectionResponse","type":"object","properties":{"data":{"type":"array","items":{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"errors":{"type":"array","description":"Array of validation or processing errors","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}}}]}}}},"400":{"description":"Could not apply custom discount","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"custom-discounts-not-enabled":{"summary":"Custom discounts not enabled for this cart","value":{"errors":[{"detail":"Custom discounts not enabled for this cart","status":400,"title":"Bad Request"}]}}}}}},"422":{"description":"Could not apply custom discount","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"limit-exceeded":{"summary":"Exceeded custom discount limit","value":{"errors":[{"detail":"Cannot exceed custom discount limit of (1) at the cart level.","status":422,"title":"Custom discount not added to cart"}]}},"cart-contains-elastic-path-promotions":{"summary":"Cart contains Elastic Path promotions","value":{"errors":[{"detail":"Custom discounts cannot be combined with Elastic Path promotions. Remove all Elastic Path promotions from the cart before adding custom discounts.","status":422,"title":"Cart contains Elastic Path promotions"}]}}}}}}}}
>
  
</StatusCodes>

---

## Bulk Add Tax Items to Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Bulk Add Tax Items to Cart"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/taxes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to bulk add tax items to cart items and bundle component products.

:::note

A cart item can only have a maximum of five tax items.
A bundle component product can only have a maximum of five tax items.

:::

### Bundle Component Taxes

To add tax items to bundle component products, include a `meta` object with `component_product_id` in each tax item:

```json
{
  "data": [
    {
      "type": "tax_item",
      "code": "GST",
      "name": "Goods and Services Tax",
      "rate": 0.1,
      "meta": {
        "component_product_id": "12345678-1234-5678-9012-123456789012"
      },
      "relationships": {
        "item": {
          "data": {
            "type": "cart_item",
            "id": "cart-item-id"
          }
        }
      }
    }
  ]
}
```

### Errors

`422 Unprocessable Entity`

In this example, when `options.add_all_or_nothing` is set to `true` and if
one of cart items is not found or has reached its maximum tax item limit,
the following error response is returned:

```json

{
            "status": 422,
            "title": "Add all or nothing.",
            "detail": "Add all or nothing set to (true). Could not bulk add tax items to cart."
        }

```

In this example, if you add more than five tax items to the same cart item,
the following error response is returned:

```json

{
            "status": 422,
            "title": "Tax item not added to cart item.",
            "detail": "Cannot exceed tax item limit of (5) on cart item.",
            "meta": {
                "id": "f88e6370-cb35-40b2-a998-c759f31dec0a"
            }
        }
```

`404`

In this example, if there is a mismatch between `cart_item`/`custom_item`
and the `relationships.item.data.type` specified in the bulk add tax item,
the following error response is returned:

```json

{
    "data": [],
    "errors": [
        {
            "status": 404,
            "title": "Tax item not added to cart item.",
            "detail": "Mismatch between bulk tax item type(cart_item) and cart item type(custom_item).",
            "meta": {
                "id": "56aab5d1-1dd4-45ed-88ed-4d0cc396b62d"
            }
        },
        {
            "status": 404,
            "title": "Tax item not added to cart item.",
            "detail": "Mismatch between bulk tax item type(cart_item) and cart item type(custom_item).",
            "meta": {
                "id": "56aab5d1-1dd4-45ed-88ed-4d0cc396b62d"
            }
        }
    ]
}

```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"CartsBulkTaxes","type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]},{"title":"CartItemRelationship","type":"object","properties":{"relationships":{"type":"object","required":["item"],"properties":{"item":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"type":{"description":"Specifies the type of item. For example, `custom_item` or `cart_item`.","type":"string","examples":["cart_item"]},"id":{"description":"Specifies the unique identifier of the `cart_item` or `custom_item` in the cart.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}}}}]}},"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}},"options":{"title":"Add All Or Nothing Options Object","type":"object","properties":{"add_all_or_nothing":{"description":"When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`.","type":"boolean","examples":[false]}}}}}]},"examples":{"bulkRateTaxItems":{"summary":"Bulk add rate-based tax items to cart items","value":{"data":[{"type":"tax_item","code":"VAT","name":"Value Added Tax","jurisdiction":"UK","rate":0.2,"relationships":{"item":{"data":{"type":"cart_item","id":"5601a4b1-9d13-42d3-8fb7-03b35169d1b6"}}}}],"options":{"add_all_or_nothing":false}}},"bulkAmountTaxItems":{"summary":"Bulk add amount-based tax items to cart and custom items","value":{"data":[{"type":"tax_item","code":"GST","name":"Goods and Services Tax","jurisdiction":"AU","amount":1000,"relationships":{"item":{"data":{"type":"cart_item","id":"1a2b3c4d-5e6f-7a8b-9c0d-abcdefabcdef"}}}},{"type":"tax_item","code":"PST","name":"Provincial Sales Tax","jurisdiction":"CA-BC","amount":250,"relationships":{"item":{"data":{"type":"custom_item","id":"9f8e7d6c-5b4a-3210-fedc-ba9876543210"}}}}],"options":{"add_all_or_nothing":true}}},"bulkBundleComponentTaxItems":{"summary":"Bulk add tax items to bundle component products using meta","value":{"data":[{"type":"tax_item","code":"GST","name":"Goods and Services Tax","jurisdiction":"AU","rate":0.1,"meta":{"component_product_id":"12345678-1234-5678-9012-123456789012"},"relationships":{"item":{"data":{"type":"cart_item","id":"22223333-4444-5555-6666-777788889999"}}}}],"options":{"add_all_or_nothing":false}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"title":"CartsBulkTaxes","type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]},{"title":"CartItemRelationship","type":"object","properties":{"relationships":{"type":"object","required":["item"],"properties":{"item":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"type":{"description":"Specifies the type of item. For example, `custom_item` or `cart_item`.","type":"string","examples":["cart_item"]},"id":{"description":"Specifies the unique identifier of the `cart_item` or `custom_item` in the cart.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}}}}]}},"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}},"options":{"title":"Add All Or Nothing Options Object","type":"object","properties":{"add_all_or_nothing":{"description":"When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`.","type":"boolean","examples":[false]}}}}}]},"examples":{"bulkAddedRateItems":{"summary":"Bulk add response with generated IDs (rate)","value":{"data":[{"id":"98c2b4de-7f33-4b3a-8f2e-8c1b2a3d4e5f","type":"tax_item","code":"VAT","name":"Value Added Tax","jurisdiction":"UK","rate":0.2,"relationships":{"item":{"data":{"type":"cart_item","id":"5601a4b1-9d13-42d3-8fb7-03b35169d1b6"}}}}]}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"title":"CartsBulkTaxes","type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]},{"title":"CartItemRelationship","type":"object","properties":{"relationships":{"type":"object","required":["item"],"properties":{"item":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"type":{"description":"Specifies the type of item. For example, `custom_item` or `cart_item`.","type":"string","examples":["cart_item"]},"id":{"description":"Specifies the unique identifier of the `cart_item` or `custom_item` in the cart.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}}}}]}},"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}},"options":{"title":"Add All Or Nothing Options Object","type":"object","properties":{"add_all_or_nothing":{"description":"When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`.","type":"boolean","examples":[false]}}}}}]},"examples":{"bulkAddedAmountAndComponentItems":{"summary":"Bulk add response with amount and component taxes","value":{"data":[{"id":"2b3c4d5e-6f70-4a8b-9c0d-1e2f3a4b5c6d","type":"tax_item","code":"GST","name":"Goods and Services Tax","jurisdiction":"AU","amount":1000,"relationships":{"item":{"data":{"type":"cart_item","id":"1a2b3c4d-5e6f-7a8b-9c0d-abcdefabcdef"}}}},{"id":"5e4d3c2b-1a0f-4b8a-9c0d-7f6e5d4c3b2a","type":"tax_item","code":"PST","name":"Provincial Sales Tax","jurisdiction":"CA-BC","amount":250,"relationships":{"item":{"data":{"type":"custom_item","id":"9f8e7d6c-5b4a-3210-fedc-ba9876543210"}}}}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Bulk Delete Custom Discounts From Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Bulk Delete Custom Discounts From Cart"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/custom-discounts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to bulk delete custom discounts from cart.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"Specifies the unique ID for the cart.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}}}}
>
  
</StatusCodes>

---

## Bulk Delete Tax Items from Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Bulk Delete Tax Items from Cart"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/taxes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to bulk delete all tax items from all cart items and bundle component products in the cart.

:::warning

This operation will remove ALL tax items from:
- All cart items in the cart
- All bundle component products within bundle cart items

:::

### Behavior

- Removes all tax items from every cart item
- Removes all tax items from every component product in bundle cart items
- If no tax items exist anywhere in the cart, returns a 404 error

### Errors

`404 Not Found`

If no tax items exist in the cart (on cart items or component products):

```json
{
    "status": 404,
    "title": "Resource Not Found",
    "detail": "No tax items exist in the cart"
}
```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}},"404":{"description":"Not Found - No tax items exist in the cart","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Bulk Update Items in Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Bulk Update Items in Cart"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartID}/items"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The bulk update feature allows shoppers to update an array of items to their cart in one action, rather than updating each item one at a time. Shoppers can update quantity and shipping group details in bulk requests. This minimizes the time for shoppers while updating items to their cart. Shoppers can even update multiple items with the same or different shipping groups to their cart.

When you update multiple items that qualify for free gifts in the cart, the corresponding free gifts for all eligible products are also automatically updated in the cart.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart that you created.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Bulk Update Carts Items","type":"object","properties":{"data":{"type":"array","items":{"anyOf":[{"title":"Update Cart Item Quantity","allOf":[{"title":"Bulk Update Carts Items (Common Properties)","type":"object","properties":{"id":{"description":"Specifies the ID of the cart item that you want to update in cart.","type":"string","format":"uuid"},"quantity":{"description":"Specifies the amount of items to update in the cart.","type":"integer","minimum":0},"type":{"description":"The type of cart item being updated.","type":"string","enum":["cart_item","custom_item"]},"custom_inputs":{"description":"Specifies the custom text to be added to a product. See [custom inputs](https://elasticpath.dev/docs/pxm/products/ep-pxm-products-api/update-a-product#using-custom-inputs-attribute).","type":"object"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"shipping_group_id":{"description":"Specifies the shipping group ID for the cart item.","type":"string","format":"uuid"}}},{"type":"object","required":["quantity","id"],"properties":{"quantity":{},"id":{}}}]},{"title":"Update Cart Item Shipping Group","allOf":[{"title":"Bulk Update Carts Items (Common Properties)","type":"object","properties":{"id":{"description":"Specifies the ID of the cart item that you want to update in cart.","type":"string","format":"uuid"},"quantity":{"description":"Specifies the amount of items to update in the cart.","type":"integer","minimum":0},"type":{"description":"The type of cart item being updated.","type":"string","enum":["cart_item","custom_item"]},"custom_inputs":{"description":"Specifies the custom text to be added to a product. See [custom inputs](https://elasticpath.dev/docs/pxm/products/ep-pxm-products-api/update-a-product#using-custom-inputs-attribute).","type":"object"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"shipping_group_id":{"description":"Specifies the shipping group ID for the cart item.","type":"string","format":"uuid"}}},{"type":"object","required":["shipping_group_id","id"],"properties":{"shipping_group_id":{},"id":{}}}]},{"title":"Update Cart Item Custom Inputs","allOf":[{"title":"Bulk Update Carts Items (Common Properties)","type":"object","properties":{"id":{"description":"Specifies the ID of the cart item that you want to update in cart.","type":"string","format":"uuid"},"quantity":{"description":"Specifies the amount of items to update in the cart.","type":"integer","minimum":0},"type":{"description":"The type of cart item being updated.","type":"string","enum":["cart_item","custom_item"]},"custom_inputs":{"description":"Specifies the custom text to be added to a product. See [custom inputs](https://elasticpath.dev/docs/pxm/products/ep-pxm-products-api/update-a-product#using-custom-inputs-attribute).","type":"object"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"shipping_group_id":{"description":"Specifies the shipping group ID for the cart item.","type":"string","format":"uuid"}}},{"type":"object","required":["custom_inputs","id"],"properties":{"custom_inputs":{},"id":{}}}]}]}},"options":{"title":"Update All Or Nothing Options Object","type":"object","properties":{"update_all_or_nothing":{"description":"When set to`true`, if an error occurs for any item, no items are updated in the cart. When set to `false`, valid items are updated in the cart and the items with errors are reported in the response. Default is `true`.","type":"boolean","examples":[false]}}}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully updated cart items","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Cart Item Response","type":"object","properties":{"id":{"description":"The unique identifier for the cart item.","type":"string","format":"uuid","readOnly":true,"examples":["4649fbb3-b8ee-4883-82c9-49a3d5fbacf1"]},"type":{"description":"The type of cart item.","type":"string","readOnly":true,"enum":["cart_item","custom_item","subscription_item","promotion_item"],"examples":["cart_item"]},"product_id":{"description":"The unique ID of the product (for cart_item type).","type":"string","format":"uuid","readOnly":true,"examples":["55cda543-f9d7-42a4-b40a-665f2e4ff7c5"]},"promotion_id":{"description":"The unique ID of the promotion (for promotion_item type).","type":"string","format":"uuid","readOnly":true,"examples":["9993387e-93ab-468f-bba9-cf13882dc52d"]},"subscription_offering_id":{"description":"The unique ID of the subscription offering for subscription items.","type":"string","format":"uuid","readOnly":true,"examples":["9c13669e-29d7-42ea-bc95-1b32399adb9d"]},"name":{"description":"The name of this item","type":"string","readOnly":true,"examples":["shirt"]},"description":{"description":"A description of the cart item.","type":"string","readOnly":true,"examples":["T-shirt."]},"sku":{"description":"The SKU of the cart item.","type":"string","readOnly":true,"examples":["sample-sku"]},"slug":{"description":"The slug of the cart item.","type":"string","readOnly":true,"examples":["sample-product"]},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if catalog_source=pim is set.","type":"string","readOnly":true,"format":"uuid","examples":["11d3f9d2-c99b-472c-96c3-51842333daea"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","readOnly":true,"examples":["pim"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","readOnly":true,"properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Product ID","type":"string"},"type":{"description":"Product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product meta information as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the cart item for bundle products.","type":"object","readOnly":true,"additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"image":{"type":"object","readOnly":true,"properties":{"mime_type":{"description":"The MIME type for the uploaded file.","type":"string","readOnly":true,"examples":["image/png"]},"file_name":{"description":"The name of the image file that was uploaded.","type":"string","readOnly":true,"examples":["shirt-trans.png"]},"href":{"description":"The link to the image.","type":"string","readOnly":true,"examples":["https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/7cc08cbb-256e-4271-9b01-d03a9fac9f0a.png"]}}},"quantity":{"description":"The quantity of the cart item.","type":"integer","readOnly":true,"examples":[1]},"auto_add_quantity":{"description":"The quantity automatically added (for gift items).","type":"integer","readOnly":true},"manage_stock":{"description":"Whether or not the quantity of the item will be checked against inventory.","type":"boolean","readOnly":true,"examples":[true]},"unit_price":{"description":"The unit price of the item.","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"value":{"description":"The total price of the item (i.e., unit * quantity).","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"discounts":{"description":"Array of discounts applied to the cart item.","type":"array","readOnly":true,"items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"}},"custom_inputs":{"description":"Custom inputs for personalized products.","type":"object","readOnly":true,"additionalProperties":true,"examples":[{"tshirt_front":"John Doe","tshirt_back":"My Custom Text"}]},"subscription_configuration":{"description":"Configuration for subscription items.","type":"object","readOnly":true,"properties":{"plan":{"description":"The subscription plan ID.","type":"string"},"pricing_option":{"description":"The subscription pricing option ID.","type":"string"}}},"links":{"type":"object","readOnly":true,"properties":{"product":{"description":"A URL related to the resource.","type":"string","examples":["https://useast.api.elasticpath.com/products/9eda5ba0-4f4a-4074-8547-ccb05d1b5981"]},"subscription_offering":{"description":"A URL related to the subscription offering resource.","type":"string"}}},"meta":{"type":"object","readOnly":true,"properties":{"display_price":{"type":"object","properties":{"with_tax":{"description":"The amount of this item after discounts and taxes are applied.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_tax":{"description":"The amount of this item after discounts are applied and before taxes.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"tax":{"description":"The amount of taxes applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"discount":{"description":"The amount of the discount applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_discount":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"original_price":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."},"discounts":{"description":"Detailed discount information.","type":"object","additionalProperties":{"type":"object","required":["amount","currency","formatted"],"properties":{"amount":{"description":"The discount amount.","type":"integer","examples":[100]},"currency":{"description":"The currency code.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted discount amount.","type":"string","examples":["$1.00"]},"constituents":{"description":"The discount constituents.","type":"object","additionalProperties":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"description":"Relationships to other resources.","readOnly":true,"type":"object","properties":{"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"custom_discounts":{"description":"Related custom discounts.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"shipping_group_id":{"description":"The shipping group ID for this item.","type":"string","readOnly":true,"examples":["eb063818-939a-458f-97a4-2601c0c2b445"]},"promotion_source":{"description":"The source of the promotion (for promotion items).","type":"string","readOnly":true,"enum":["rule-promotion"],"examples":["rule-promotion"]},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"location":{"description":"The stock location for this item.","type":"string","readOnly":true,"examples":["warehouse-1"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true}}}},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"type":"object","properties":{"automatic":{"type":"boolean"},"description":{"type":"string"},"end":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"promotion_type":{"type":"string"},"promotion_source":{"type":"string","description":"The source of the promotion"},"start":{"type":"string","format":"date-time"},"type":{"type":"string","const":"promotion"}}}},"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}}}},"meta":{"type":"object","description":"Additional meta information about the cart items collection.","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"balance_owing":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"messages":{"type":"array","description":"Optional array of informational messages that provide feedback about operations performed on the cart items, such as promotions added or discounts applied. This field is only present when there are relevant messages to display.\n","items":{"type":"object","properties":{"source":{"type":"object","description":"Identifies the cart item that triggered this message","properties":{"type":{"type":"string","description":"The type of the source item"},"id":{"type":"string","description":"The unique identifier of the source item"},"code":{"type":"string","description":"The promotion code (present when source type is promotion)"}},"required":["type","id"]},"title":{"type":"string","description":"A short descriptive title for the message"},"description":{"type":"string","description":"A detailed description of the message"}},"required":["title","description"]}},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"},"auto_add":{"type":"boolean","description":"Whether this promotion should be automatically added"},"targets":{"description":"Array of promotion targets (alternative structure)","type":"array","items":{"type":"object","properties":{"cart_item_id":{"type":"string","description":"The cart item ID for this target"},"quantity":{"type":"integer","description":"The quantity for this target"},"skus":{"type":"array","description":"Array of SKU codes for this target","items":{"type":"string"}}}}}}}}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"required":["data"],"title":"CartItemCollectionResponse"}}}},"400":{"description":"Insufficient Stock","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Insufficient Stock","value":{"errors":[{"detail":"There is not enough stock to add Fry Pan to your cart","meta":{"id":"0e5bae32-cc71-4ede-8d7d-cb662e90c542"},"status":400,"title":"Insufficient stock"}]}}}}}},"403":{"description":"Unauthorized call","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"No permissions to use custom attributes","value":{"errors":[{"detail":"No permissions to fulfill this request with cart item custom_attributes","meta":{"id":"0e5bae32-cc71-4ede-8d7d-cb662e90c542"},"status":403,"title":"Unauthorised call"}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Not Found","value":{"errors":[{"detail":"Item was not found in the cart","meta":{"id":"0e5bae32-cc71-4ede-8d7d-cb662e90c542","ids":["0e5bae32-cc71-4ede-8d7d-cb662e90c542"]},"status":404,"title":"Not Found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Could not apply EP promotion with the given code","value":{"errors":[{"detail":"The cart is configured to use custom discounts","meta":{"code":"10_OFF","ids":["0e5bae32-cc71-4ede-8d7d-cb662e90c542"]},"status":422,"title":"Could not apply EP promotion with the given code"}]}}}}}}}}
>
  
</StatusCodes>

---

## Cancel a Transaction

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cancel a Transaction"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/orders/{orderID}/transactions/{transactionID}/cancel"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to cancel or void a pending or authorized transaction. The transaction can be canceled or voided when it is in `pending` and `completed` statuses.

:::caution

This endpoint works only for Stripe and PayPal and does not work for manual gateway.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The unique identifier of the order.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"transactionID","in":"path","description":"The unique identifier of the transaction to be canceled or voided.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"OrdersTransactionsCancelRequest","type":"object","properties":{"data":{"type":"object","properties":{"options":{"type":"object"},"reason":{"description":"Specifies the reason for canceling the transaction. The reason may include `duplicate`, `fraudulent`, `requested_by_customer`, or `abandoned`.","type":"string","examples":["requested_by_customer"]}}}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{"type":"object","title":"TransactionResponse","properties":{"id":{"description":"The ID of the transaction.","type":"string","format":"uuid","readOnly":true},"reference":{"description":"The payment gateway reference.","type":"string","examples":["manual"]},"name":{"description":"A custom name associated with the payment method.","type":"string","examples":["payment method name"]},"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.","type":"string","examples":["custom reference"]},"gateway":{"description":"The name of the payment gateway used.","type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents","stripe_platform_account"]},"amount":{"description":"The amount for this transaction.","type":"number","examples":[10000]},"refunded_amount":{"description":"The refunded amount.","type":"number","examples":[0]},"currency":{"description":"The transaction currency.","type":"string","examples":["USD"]},"transaction_type":{"description":"The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`.","type":"string","enum":["purchase","authorize","capture","refund"]},"type":{"description":"The type of object being returned.","type":"string"},"status":{"description":"The status provided by the gateway for this transaction, such as `complete` or `failed`.","type":"string","examples":["complete"]},"payment_details":{"description":"Payment gateway specific details.","type":"object","properties":{"detailed_status":{"description":"Detailed status from the payment gateway.","type":"string"}}},"failure_details":{"description":"Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information.","title":"FailureDetails","type":"object","properties":{"code":{"description":"Machine-readable failure or error code from the payment gateway.","type":"string","examples":["2"]},"reason":{"description":"Human-readable failure reason or error message from the payment gateway.","type":"string","examples":["This transaction has been declined."]}}},"payment_intent":{"description":"Payment intent details.","type":"object","additionalProperties":true},"capture_mechanism":{"description":"The mechanism used for capturing the transaction.","type":"string","enum":["automatic","manual"]},"refund_mechanism":{"description":"The mechanism used for refunding the transaction.","type":"string","enum":["automatic","manual"]},"client_parameters":{"description":"Client-specific parameters for payment processing.","type":"object","properties":{"redirect_url":{"description":"URL to redirect the client after payment.","type":"string"},"secret":{"description":"Client secret for payment processing.","type":"string"},"token":{"description":"Client token for payment processing.","type":"string"}}},"next_actions":{"description":"Array of next actions for the transaction.","type":"array","items":{"type":"string"}},"relationships":{"type":"object","properties":{"order":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Represents the type of the object being returned. It is always `order`.","type":"string","examples":["order"]},"id":{"description":"The ID of the order.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}},"meta":{"type":"object","properties":{"display_price":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"display_refunded_amount":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}}}}},"required":["data"],"title":"TransactionEntityResponse"}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Capture a Transaction

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Capture a Transaction"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/orders/{orderID}/transactions/{transactionID}/capture"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to capture a previously authorized payment. In this step, you can also pass in a custom reference, such as the payment reference from your chosen gateway.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The UUID of the order.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"transactionID","in":"path","description":"The UUID of the transaction to capture.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"OrdersTransactionsCaptureRequest","type":"object","properties":{"data":{"type":"object","properties":{"options":{"type":"object","properties":{"soft_descriptor":{"type":"string"},"note_to_payer":{"type":"string"}}}}}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"TransactionResponse","properties":{"id":{"description":"The ID of the transaction.","type":"string","format":"uuid","readOnly":true},"reference":{"description":"The payment gateway reference.","type":"string","examples":["manual"]},"name":{"description":"A custom name associated with the payment method.","type":"string","examples":["payment method name"]},"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.","type":"string","examples":["custom reference"]},"gateway":{"description":"The name of the payment gateway used.","type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents","stripe_platform_account"]},"amount":{"description":"The amount for this transaction.","type":"number","examples":[10000]},"refunded_amount":{"description":"The refunded amount.","type":"number","examples":[0]},"currency":{"description":"The transaction currency.","type":"string","examples":["USD"]},"transaction_type":{"description":"The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`.","type":"string","enum":["purchase","authorize","capture","refund"]},"type":{"description":"The type of object being returned.","type":"string"},"status":{"description":"The status provided by the gateway for this transaction, such as `complete` or `failed`.","type":"string","examples":["complete"]},"payment_details":{"description":"Payment gateway specific details.","type":"object","properties":{"detailed_status":{"description":"Detailed status from the payment gateway.","type":"string"}}},"failure_details":{"description":"Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information.","title":"FailureDetails","type":"object","properties":{"code":{"description":"Machine-readable failure or error code from the payment gateway.","type":"string","examples":["2"]},"reason":{"description":"Human-readable failure reason or error message from the payment gateway.","type":"string","examples":["This transaction has been declined."]}}},"payment_intent":{"description":"Payment intent details.","type":"object","additionalProperties":true},"capture_mechanism":{"description":"The mechanism used for capturing the transaction.","type":"string","enum":["automatic","manual"]},"refund_mechanism":{"description":"The mechanism used for refunding the transaction.","type":"string","enum":["automatic","manual"]},"client_parameters":{"description":"Client-specific parameters for payment processing.","type":"object","properties":{"redirect_url":{"description":"URL to redirect the client after payment.","type":"string"},"secret":{"description":"Client secret for payment processing.","type":"string"},"token":{"description":"Client token for payment processing.","type":"string"}}},"next_actions":{"description":"Array of next actions for the transaction.","type":"array","items":{"type":"string"}},"relationships":{"type":"object","properties":{"order":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Represents the type of the object being returned. It is always `order`.","type":"string","examples":["order"]},"id":{"description":"The ID of the order.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}},"meta":{"type":"object","properties":{"display_price":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"display_refunded_amount":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}}}}},"required":["data"],"title":"TransactionEntityResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Required field missing","value":{"errors":[{"detail":"Request could not be processed","status":"400","title":"Bad Request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Cart Items

Products added to a cart are referred to as a `cart_item`.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Cart Management

A Cart contains the product and custom cart items that a user intends to purchase. After a Cart is ready for Checkout, you can use the [Checkout endpoint](/docs/api/carts/checkout) to convert the cart to an order.

:::note

- Adding, modifying, or removing any cart items, custom items, or promotions always returns the cart meta, calculated using the calculation method. This is useful to update the client with up-to-date totals.
- We will automatically delete carts 7 days after they were last updated.
- If you do not pass a `X-MOLTIN-CURRENCY` header specifying what currency you would like the cart to use, the products in the cart are converted to your default currency.

:::

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Cart Settings

Use Cart Settings to configure cart behavior for your store, including cart expiry, custom discounts, rule promotions, deferred inventory checks, and cart visibility for admins.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Carts, Checkout, Orders Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/carts/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Carts, Checkout, Orders Introduction"}
>
</Heading>

A cart contains a list of the products that a shopper adds to the cart while browsing your catalog. In the context of a cart, a selected product is called a cart item.

A cart item identifies the product, the product price, the quantity selected, and the total price for the quantity selected. The cart displays a running total of the cost for the selected products plus the calculated tax.

You can allow your shoppers to add custom text to a product when adding an item to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized. See [Add product to cart](/docs/api/carts/manage-carts#add-product-to-cart).

After a shopper checks out, the cart is converted to an order, and you can manually delete the cart. If you don't delete the cart, it is purged automatically after seven days.

The preview cart feature allows you to set a future date for your shopping cart and view the promotions that will be available during that time period. This feature enables you to validate your promotion settings and observe how they will be applied in the cart. See [Create a Preview Cart](/docs/api/carts/create-a-cart#preview-cart).

The following diagram shows a typical cart workflow:

![Shows a cart workflow, starting from adding the first item to a cart, through cart creation and checkout](/assets/cart-workflow.png)

### Multiple Carts

Buyers often make purchases based on jobs that they need to perform or outcomes they need to achieve and therefore require more than one shopping cart. For example, a corporate buyer places orders for multiple locations. Each location has a different frequency of ordering and require different products. The buyer can create one cart per location, fill the carts, and then check out the carts quickly. Similarly, shoppers can also create multiple carts for the ease of managing various shopping experiences, such as birthdays or holidays.

Each cart is discrete and separate. Any updates or changes to one cart has no effect on the other carts. A cart persists, that is, it stays with the buyer or shopper even after they use the cart in a checkout. Carts remain available after a checkout.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: 
  
    URL: [https://elasticpath.com](https://elasticpath.com)
  

  
    License
  
    MIT

---

## Checkout API

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Checkout API"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/checkout"}
  context={"endpoint"}
>
  
</MethodEndpoint>

When a Cart is ready for checkout, you can convert the cart to an order. The cart remains and can be modified and checked out again if required.

A cart can be checked out with a customer ID, customer object, or with an account by authenticating with the `Client Credentials Token`.

After a successful checkout, a response that contains the order is returned. If the cart is linked to a shipping group, the shipping group is also associated with the order after checkout.

You can checkout using one of the following methods:
- **Customer ID**: You can checkout a cart with an existing customer ID.
- **Guest Checkout** (Checkout with Customer Object): You can checkout a cart with an associated customer name and email.
- **Checkout with Account**: The shopper authenticates with the `Client Credentials` Token.
- **Checkout with Account Management Authentication Token**: The shopper authenticates with the `Implicit Token` and the `EP-Account-Management-Authentication-Token`.

:::note

- The cart currency is set when the first item is added to the cart.
- The product being added to the cart requires a price in the same currency as the other items in the cart. The API returns a 400 error if a price is not defined in the correct currency.
- To ensure that a free gift is automatically applied to an order, set the promotion to automatic. The checkout process will not be successful if free gift items are out of stock. See [Errors](#errors) section.

:::

:::caution

- By default, carts are automatically deleted 7 days after the last update. You can change this setting by [updating cart settings](/docs/api/carts/put-v-2-settings-cart).
- Your inventory is modified during checkout and payment of an order. For more information about the changes in the inventory, see the [Inventory](/docs/api/pxm/inventory/inventories-introduction) section.

:::

 You can pass `order_number` and `external_ref` in the checkout endpoint or when [updating an order](/docs/api/carts/update-an-order). The `order_number` is an optional, user-managed field that is used as an alternative to `order_id`. When processing transactions through Authorize.net, the `order_number` is sent instead of the `order_id`, and it will appear in the invoice number section. If no `order_number` is provided, the `order_id` is sent to Authorize.net on payment by default. There are no duplication restrictions on the `order_number` value.

### Next Steps

After a cart has been converted to an Order using either of the previous methods, you most likely want to capture payment for order. See [Paying for an Order](/docs/api/carts/payments).

### Errors

The following error response is returned during checkout when an eligible item is added to the cart, and the free gift is out of stock.

```json
{
    "errors": [
        {
            "status": 400,
            "title": "Insufficient stock",
            "detail": "There is not enough stock to add gift2 to your cart",
            "meta": {
                "id": "f2b68648-9621-45a3-aed6-1b526b0f5beb",
                "sku": "gift2"
            }
        }
    ]
}
```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The ID of the cart that you want to checkout.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"EP-Account-Management-Authentication-Token","in":"header","description":"An account management authentication token that identifies the authenticated account member.","style":"simple","schema":{"type":"string","examples":["{{accountToken}}"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"oneOf":[{"title":"Customer Checkout","type":"object","properties":{"data":{"type":"object","properties":{"order_number":{"description":"A user-managed, optional field used as an alternative to the existing `order_id`. If provided, the order-number will be sent to Authorize.net instead of the `order_id`, and will appear as the invoice number in Authorize.net transactions.","type":"string"},"external_ref":{"description":"An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string"},"customer":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string"},"email":{"description":"The email of the customer.","type":"string"},"name":{"description":"The name of the customer.","type":"string"}}},"billing_address":{"title":"BillingAddress","description":"Billing address information. You must specify at least one of region (state/province) or county.\n","anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}],"examples":[{"first_name":"John","last_name":"Doe","company_name":"John Doe Enterprises","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB"}]},"shipping_address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]}}}}},{"title":"Account Checkout","type":"object","properties":{"data":{"type":"object","properties":{"order_number":{"description":"A user-managed, optional field used as an alternative to the existing `order_id`. If provided, the order-number will be sent to Authorize.net instead of the `order_id`, and will appear as the invoice number in Authorize.net transactions.","type":"string"},"external_ref":{"description":"An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string"},"account":{"type":"object","properties":{"id":{"description":"The account ID.","type":"string"},"member_id":{"description":"The account member ID.","type":"string"}}},"contact":{"type":"object","properties":{"name":{"description":"The name of the account member.","type":"string"},"email":{"description":"The email address of the account member.","type":"string","format":"email"}}},"billing_address":{"title":"BillingAddress","description":"Billing address information. You must specify at least one of region (state/province) or county.\n","anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}],"examples":[{"first_name":"John","last_name":"Doe","company_name":"John Doe Enterprises","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB"}]},"shipping_address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]}}}}}]},"examples":{"CheckoutWithCustomerID":{"summary":"Checkout with Customer ID","value":{"data":{"order_number":"order-1234","external_ref":"e-123456789","customer":{"id":"c8c1c511-beef-4812-9b7a-9f92c587217c"},"billing_address":{"first_name":"John","last_name":"Doe","company_name":"Moltin","line_1":"1234 Disney Drive","line_2":"Disney Resort","line_3":"Building C","city":"Anaheim","county":"Orange","region":"CA","postcode":"92802","country":"US"},"shipping_address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"Moltin","line_1":"1234 Disney Drive","line_2":"Disney Resort","line_3":"Building C","city":"Anaheim","county":"Orange","region":"CA","postcode":"92802","country":"US","instructions":"Leave in porch"}}}},"CheckoutWithCustomerObject":{"summary":"Guest Checkout (Checkout with Customer Object)","value":{"data":{"order_number":"order-1234","external_ref":"e-123456789","customer":{"email":"john@moltin.com","name":"John Doe"},"billing_address":{"first_name":"John","last_name":"Doe","company_name":"Moltin","line_1":"1234 Disney Drive","line_2":"Disney Resort","line_3":"Building C","city":"Anaheim","county":"Orange","region":"CA","postcode":"92802","country":"US"},"shipping_address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"Moltin","line_1":"1234 Disney Drive","line_2":"Disney Resort","line_3":"Building C","city":"Anaheim","county":"Orange","region":"CA","postcode":"92802","country":"US","instructions":"Leave in porch"}}}},"CreateCheckoutWithAccount":{"summary":"Create Checkout with Account","value":{"data":{"order_number":"order-1234","external_ref":"e-123456789","account":{"id":"8cee1b9e-3e39-4d5f-bd4a-86cdb985c6ee","member_id":"338f84bf-e6c9-4704-9f33-2708addd462b"},"contact":{"email":"john@email.com","name":"John Doe"},"billing_address":{"first_name":"John","last_name":"Doe","company_name":"ElasticPath","line_1":"1234 Disney Drive","line_2":"Disney Resort","line_3":"Building C","city":"Anaheim","county":"Orange","region":"CA","postcode":"92802","country":"US"},"shipping_address":{"first_name":"John","last_name":"Doe","company_name":"ElasticPath","phone_number":"(555) 555-1234","line_1":"1234 Disney Drive","line_2":"Disney Resort","line_3":"Building C","city":"Anaheim","county":"Orange","region":"CA","postcode":"92802","country":"US","instructions":"Leave in porch"}}}},"CreateCheckoutWithAccountManagementAuthenticationToken":{"summary":"Create Checkout with Account Management Authentication Token","value":{"data":{"order_number":"order-1234","external_ref":"e-123456789","contact":{"email":"john@email.com","name":"John Doe"},"billing_address":{"first_name":"John","last_name":"Doe","company_name":"ElasticPath","line_1":"1234 Disney Drive","line_2":"Disney Resort","line_3":"Building C","city":"Anaheim","county":"Orange","region":"CA","postcode":"92802","country":"US"},"shipping_address":{"first_name":"John","last_name":"Doe","company_name":"ElasticPath","phone_number":"(555) 555-1234","line_1":"1234 Disney Drive","line_2":"Disney Resort","line_3":"Building C","city":"Anaheim","county":"Orange","region":"CA","postcode":"92802","country":"US","instructions":"Leave in porch"}}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"OK","content":{"application/json":{"schema":{"title":"OrderEntityResponse","type":"object","properties":{"data":{"title":"OrderResponse","type":"object","properties":{"type":{"description":"Specifies the type of object being returned. You must use `order`.","type":"string","const":"order"},"order_number":{"description":"Specifies a user-managed, optional field used as an alternative to the existing `order_id`. If provided, the order-number will be sent to Authorize.net instead of the `order_id`, and will appear as the invoice number in Authorize.net transactions.","type":"string","examples":[1234]},"external_ref":{"description":"An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","examples":["e-123456789"]},"id":{"description":"Specifies the unique identifier of the order.","type":"string","format":"uuid","readOnly":true,"examples":["aa854b8f-5930-476d-951a-e9b9cfbdefb1"]},"status":{"description":"Specifies the status of the order, such as `incomplete`, `complete`, `processing`, or `cancelled`.","type":"string","enum":["complete","incomplete","cancelled","processing"]},"payment":{"description":"Specifies the status of the payment, such as `unpaid`, `authorized`, `paid`, or `refunded`.","type":"string","enum":["authorized","paid","unpaid","refunded","partially_paid","partially_authorized"]},"shipping":{"description":"Specifies the status of the shipment, such as `fulfilled` or `unfulfilled`.","type":"string","enum":["unfulfilled","fulfilled"]},"anonymized":{"description":"Specifies if the order is anonymized.","type":"boolean","examples":[false]},"payment_intent_id":{"description":"Stripe Payment Intent ID.  Please see Stripe's Payment Intent [documentation](https://docs.stripe.com/api/payment_intents) for more information on Payment Intents.","type":"string","examples":["pi_3MtwBwLkdIwHu7ix28a3tqPa"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"links":{"type":"object"},"meta":{"title":"OrderMeta","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this order was created.","type":"string"},"updated_at":{"description":"The date this order was last updated.","type":"string"},"fully_paid_at":{"description":"The date this order was fully paid. Only present for orders with payment status 'paid'.","type":"string"}},"title":"OrderTimestamps"},"display_price":{"description":"Order pricing information including amounts, tax, discounts, and payment details.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}}},"is_manual":{"description":"Specifies if the order was created manually.","type":"boolean"}}},"billing_address":{"title":"BillingAddress","description":"Billing address information. You must specify at least one of region (state/province) or county.\n","anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}],"examples":[{"first_name":"John","last_name":"Doe","company_name":"John Doe Enterprises","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB"}]},"contact":{"title":"Contact","type":"object","properties":{"email":{"description":"The email address of the contact.","type":"string","examples":["johndoe@email.com"]},"name":{"description":"The name of the contact.","type":"string","examples":["John Doe"]}}},"customer":{"title":"Customer","type":"object","properties":{"name":{"description":"The name of the customer.","type":"string","examples":["John Doe"]},"email":{"description":"The email address of the customer.","type":"string","format":"email","examples":["john.doe@example.com"]},"id":{"description":"The unique identifier of the customer.","type":"string","format":"uuid","examples":["e5a0d684-a4af-4919-a348-f66b0b4955e0"]}}},"shipping_address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"relationships":{"type":"object","properties":{"items":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"customer":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account_member":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"store":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}},"included":{"description":"Optional included data such as order items, tax items, custom discounts, and promotions.\n","type":"object","properties":{"items":{"description":"Array of order items included in the response.","type":"array","items":{"title":"OrderItemResponse","type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["68bf8510-bebf-47b1-96ba-8a9930c7d928"]},"quantity":{"description":"The quantity of this item were ordered.","type":"number","examples":[1]},"product_id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["4e9c6098-9701-4839-a69c-54d8256d9012"]},"subscription_offering_id":{"description":"The unique identifier for the subscription offering for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["69a39623-e681-415e-83c0-e1281010c77d"]},"name":{"description":"The name of this order item.","type":"string","examples":["Product 123"]},"sku":{"description":"The SKU code for the order item.","type":"string","examples":["IFD-1"]},"location":{"description":"The stock location for this order item.","type":"string","readOnly":true},"unit_price":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"value":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"discounts":{"type":"array","items":{"title":"DiscountData","type":"object","properties":{"amount":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"code":{"type":"string"},"id":{"type":"string","format":"uuid","readOnly":true},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}}}},"links":{"type":"object"},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discounts":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$1.00"]},"constituents":{"type":"object","description":"Detailed breakdown of discount constituents by ID","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","description":"The discount amount"},"currency":{"type":"string","description":"The currency code"},"formatted":{"type":"string","description":"The formatted discount amount"}}}}}}},"original_price":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"type":"object","properties":{"cart_item":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this item.","type":"string","format":"uuid","readOnly":true,"examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}},"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.","type":"string","examples":["default"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","examples":["pim","legacy"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Component product ID","type":"string"},"type":{"description":"Component product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product metadata as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price information as a generic object","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the bundle product.","type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"custom_inputs":{"description":"Custom inputs for the order item as a generic object","type":"object","additionalProperties":true},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true},"shipping_group_id":{"description":"The shipping group ID for the order item","type":"string"},"promotion_source":{"description":"The promotion source for the order item","type":"string"},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"subscription_configuration":{"description":"Subscription configuration for the order item","type":"object","properties":{"plan":{"description":"Subscription plan details","type":"string"},"pricing_option":{"description":"Pricing option for the subscription","type":"string"}}}}}},"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}},"custom_discounts":{"description":"Array of custom discounts included in the response.","type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"description":"Array of promotions included in the response.","type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Checkout

The checkout workflow ties together many of the key concepts covered in this section. When a customer initiates the checkout process, an order is created from the cart. The order is incomplete until after a successful payment is made. A complete order can be shipped and the product deducted from inventory counts.

![Checkout workflow](/assets/checkout-flow.png)

### Summary of the checkout workflow

1. Add a product to a cart. A cart and its reference number is generated.
2. Manage the cart items. For example, you might add items, remove items, and change quantities.
3. Check out the cart. An incomplete order is created.
4. Pay for an order: provide billing and shipping details, if you are a new customer. The order is now in the processing status.
5. If using a manual gateway, after you authorize and capture it, Composable Commerce considers the order complete. If you use a third-party integration supported by Composable Commerce (such as Stripe), after the third-party gateway authorizes and captures the payment, the order becomes complete. Usually capture does not occur at the same time as authorization. For more information, see the Capture section.
6. After the order is shipped, you can manually flag it as fulfilled.

### Carts

When a product is added to a cart, a cart is generated together with its unique reference ID that on checkout becomes a part of the order ID. If you are using our JavaScript software development kit, generating a cart reference ID is done for you; otherwise, add a cart reference generator to your functionality.

### Promotions and custom items

Optionally, apply a promotion code on a cart, or add custom_items to modify the product price (typically to handle taxes, customs, or shipping).

### Checkout

You can checkout a cart with an associated customer name and email (customer object). Typically, this would be used for new customers or ones that prefer to shop as guests. Use the `customer.id` checkout option to checkout for an existing customer. After a successful checkout is completed, the response contains an order.

Email addresses that either begin or end with a period, or contain consecutive periods, are considered invalid, resulting in the following error:
```json
"errors": [
  {
      "status": 400,
      "source": "data.customer.email",
      "title": "format",
      "detail": "Does not match format 'email'"
  }
]
  ```

### Payments

On checkout, an incomplete order is created. You can then use a third-party integration to handle your payment gateway. If the payment gateway is supported by Composable Commerce, such as Stripe, the payment is processed externally but handled internally. When a successful validation is returned, Composable Commerce flags the order as complete.

If you are using a payment method not officially supported by Composable Commerce, the gateway needs to be implemented and handled manually. After the payment has been authorized and captured either through Commerce Manager or API, the status of an order becomes complete.

### Shipping

The status of an order and the status of shipping are handled separately, and so an order can be complete but not shipped. Orders that have not been shipped yet have a status of unfulfilled. This flag is generated automatically by Composable Commerce when an order is created. Currently, you can only update the shipping status manually, through the API. After the order is shipped, flag its shipping status as fulfilled.

### Inventory

If enabled, you can manage your stock. As such, your stock is automatically updated as soon as a product is checked out.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Confirm Order

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Confirm Order"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/orders/{orderID}/confirm"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to confirm an order. Confirming an order finalizes it and makes it ready for processing.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The unique identifier of the order to confirm.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Order confirmed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"TransactionResponse","properties":{"id":{"description":"The ID of the transaction.","type":"string","format":"uuid","readOnly":true},"reference":{"description":"The payment gateway reference.","type":"string","examples":["manual"]},"name":{"description":"A custom name associated with the payment method.","type":"string","examples":["payment method name"]},"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.","type":"string","examples":["custom reference"]},"gateway":{"description":"The name of the payment gateway used.","type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents","stripe_platform_account"]},"amount":{"description":"The amount for this transaction.","type":"number","examples":[10000]},"refunded_amount":{"description":"The refunded amount.","type":"number","examples":[0]},"currency":{"description":"The transaction currency.","type":"string","examples":["USD"]},"transaction_type":{"description":"The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`.","type":"string","enum":["purchase","authorize","capture","refund"]},"type":{"description":"The type of object being returned.","type":"string"},"status":{"description":"The status provided by the gateway for this transaction, such as `complete` or `failed`.","type":"string","examples":["complete"]},"payment_details":{"description":"Payment gateway specific details.","type":"object","properties":{"detailed_status":{"description":"Detailed status from the payment gateway.","type":"string"}}},"failure_details":{"description":"Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information.","title":"FailureDetails","type":"object","properties":{"code":{"description":"Machine-readable failure or error code from the payment gateway.","type":"string","examples":["2"]},"reason":{"description":"Human-readable failure reason or error message from the payment gateway.","type":"string","examples":["This transaction has been declined."]}}},"payment_intent":{"description":"Payment intent details.","type":"object","additionalProperties":true},"capture_mechanism":{"description":"The mechanism used for capturing the transaction.","type":"string","enum":["automatic","manual"]},"refund_mechanism":{"description":"The mechanism used for refunding the transaction.","type":"string","enum":["automatic","manual"]},"client_parameters":{"description":"Client-specific parameters for payment processing.","type":"object","properties":{"redirect_url":{"description":"URL to redirect the client after payment.","type":"string"},"secret":{"description":"Client secret for payment processing.","type":"string"},"token":{"description":"Client token for payment processing.","type":"string"}}},"next_actions":{"description":"Array of next actions for the transaction.","type":"array","items":{"type":"string"}},"relationships":{"type":"object","properties":{"order":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Represents the type of the object being returned. It is always `order`.","type":"string","examples":["order"]},"id":{"description":"The ID of the order.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}},"meta":{"type":"object","properties":{"display_price":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"display_refunded_amount":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}}}}},"required":["data"],"title":"TransactionEntityResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Request could not be processed\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Order not found","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Order not found\",\n      \"status\": \"404\",\n      \"title\": \"Not Found\"\n    }\n  ]\n}\n"}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Validation error","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Order cannot be confirmed in its current state\",\n      \"status\": \"422\",\n      \"title\": \"Unprocessable Entity\"\n    }\n  ]\n}\n"}}}}}}}}
>
  
</StatusCodes>

---

## Confirm Payment

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Confirm Payment"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/orders/{orderID}/transactions/{transactionID}/confirm"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Confirm Payment serves as a mechanism to synchronize transaction information from the third-party payment provider back to our system. This ensures that Composable Commerce accurately reflects the values from the payment provider.

### Handling 3D Secure Validations for Stripe Payments

For Stripe Payments requiring 3D Secure validation, the transaction response will include the `client_parameters` object, which provides credentials to support validation of these payment requests on the payment provider's side. We recommend using the Stripe's client libraries to manage these 3D Secure validations. Once the validation succeeds, proceed with a confirmation request to sync the validated transaction into Composable Commerce and continue with the payment process.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The unique identifier of the order.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"transactionID","in":"path","description":"The unique identifier of the transaction.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"OrdersTransactionsConfirmRequest","type":"object","properties":{"data":{"type":"object"}}}]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"TransactionResponse","properties":{"id":{"description":"The ID of the transaction.","type":"string","format":"uuid","readOnly":true},"reference":{"description":"The payment gateway reference.","type":"string","examples":["manual"]},"name":{"description":"A custom name associated with the payment method.","type":"string","examples":["payment method name"]},"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.","type":"string","examples":["custom reference"]},"gateway":{"description":"The name of the payment gateway used.","type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents","stripe_platform_account"]},"amount":{"description":"The amount for this transaction.","type":"number","examples":[10000]},"refunded_amount":{"description":"The refunded amount.","type":"number","examples":[0]},"currency":{"description":"The transaction currency.","type":"string","examples":["USD"]},"transaction_type":{"description":"The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`.","type":"string","enum":["purchase","authorize","capture","refund"]},"type":{"description":"The type of object being returned.","type":"string"},"status":{"description":"The status provided by the gateway for this transaction, such as `complete` or `failed`.","type":"string","examples":["complete"]},"payment_details":{"description":"Payment gateway specific details.","type":"object","properties":{"detailed_status":{"description":"Detailed status from the payment gateway.","type":"string"}}},"failure_details":{"description":"Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information.","title":"FailureDetails","type":"object","properties":{"code":{"description":"Machine-readable failure or error code from the payment gateway.","type":"string","examples":["2"]},"reason":{"description":"Human-readable failure reason or error message from the payment gateway.","type":"string","examples":["This transaction has been declined."]}}},"payment_intent":{"description":"Payment intent details.","type":"object","additionalProperties":true},"capture_mechanism":{"description":"The mechanism used for capturing the transaction.","type":"string","enum":["automatic","manual"]},"refund_mechanism":{"description":"The mechanism used for refunding the transaction.","type":"string","enum":["automatic","manual"]},"client_parameters":{"description":"Client-specific parameters for payment processing.","type":"object","properties":{"redirect_url":{"description":"URL to redirect the client after payment.","type":"string"},"secret":{"description":"Client secret for payment processing.","type":"string"},"token":{"description":"Client token for payment processing.","type":"string"}}},"next_actions":{"description":"Array of next actions for the transaction.","type":"array","items":{"type":"string"}},"relationships":{"type":"object","properties":{"order":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Represents the type of the object being returned. It is always `order`.","type":"string","examples":["order"]},"id":{"description":"The ID of the order.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}},"meta":{"type":"object","properties":{"display_price":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"display_refunded_amount":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}}}}},"required":["data"],"title":"TransactionEntityResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Required field missing","value":{"errors":[{"detail":"Request could not be processed","status":"400","title":"Bad Request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Cart"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a cart. Call this endpoint each time a customer creates a cart.

Each shopper can have multiple carts. Use the carts API to create a cart. The carts are distinct from one another. Shoppers can add different items to their carts. They can check out one of the carts without affecting the content or status of their other carts.

After the shopper checks out the cart, the cart remains available to the shopper. The cart is persistent and stays with the shopper after it is used.

You can create a cart to specify custom discounts. You can enable custom discounts when the `discount_settings.custom_discounts_enabled` field is set to `true`. Default is set from cart discount settings for the store. See [Update Cart Settings](/docs/api/carts/put-v-2-settings-cart).

You can also create a cart when inventory checks are not performed until checkout by setting the `inventory_settings.defer_inventory_check` field to `true`. Again the default is set from cart discount settings for the store. See [Update Cart Settings](/docs/api/carts/put-v-2-settings-cart).

### Preview Cart

You can set a future date for your shopping cart and view the promotions that will be available during that time period. This feature enables you to validate your promotion settings and observe how they will be applied in the cart.

:::caution
- Once the cart is in preview mode, you cannot revert it to a regular cart.
- Carts with `snapshot_date` are same as preview carts.
- You cannot checkout a cart that includes a `snapshot_date`.
- To delete a promotion preview cart, use [Delete a cart](/docs/api/carts/delete-a-cart) endpoint.
- The promotion preview cart has the same expiration time as a regular cart based on the store's [cart settings](/docs/api/carts/put-v-2-settings-cart).
- Preview cart interactions skip inventory checks and events, allowing users to preview future carts without impacting related external systems.
:::

### Custom Attributes
You can create custom attributes for the cart object to include additional information, enabling promotions that target specific cart attributes.
For example:
```
"custom_attributes":{
  "membership": {
    "type": "string",
    "value": "VIP"
  }
}
```
See [adding cart custom attributes in promotions builder](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#adding-cart-custom-attributes)

Cart custom attributes remain with the corresponding cart for the extent of its lifecycle.  These custom attributes carry over to the resulting order objects on checkout and those on carts are deleted with their carts upon cart deletions.
Custom attributes can be updated or removed using a PUT request. To delete specific custom attributes, simply exclude the unwanted attribute objects from the PUT request body.

### Contact Email
You can attach an email to carts via the `contact.email` field.  These values help identify guest shopper carts and, in the case of promotions with maximum usage settings for guest and registered shopper, track per-shopper promotion usages.
See [Create Max Uses Per Shopper Promotion Codes](/docs/promotions-builder/promotions-builder-codes/create-max-use-limit-promotion-codes)

For example:
```
"contact": {
  "email": "tester@email.com"
}
```

Please note, this value is not supported for registered shopper carts (that is, carts with accounts or customers associated), as these carts already have email values associated via the shopper details.  Accordingly, requests to add contact email information to registered shopper carts (and vice versa) result in error messages.

### Errors

- `400 Bad Request` : This is returned when the submitted request does not adhere to the expected API contract for the endpoint.

   - For example, in the case of string fields, this error might indicate issues in the length or format of submitted strings. For more information about valid string fields, refer to Safe Characters section.
   - In the case of preview carts (those with `snapshot_date`), an error is returned for invalid actions, such as removing the preview date, setting a preview date in the past, or attempting to checkout a cart with a `snapshot_date`.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"EP-Account-Management-Authentication-Token","in":"header","description":"An Account Management Authentication token for the account to be associated with the cart.","style":"simple","required":false,"schema":{"type":"string","examples":["{{accountToken}}"]}},{"name":"X-Moltin-Customer-Token","in":"header","description":"A customer token for the customer to be associated with the cart.","style":"simple","required":false,"schema":{"type":"string","examples":["{{customerToken}}"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"title":"CartsRequest","type":"object","properties":{"data":{"type":"object","properties":{"description":{"type":"string","description":"The cart description.","examples":["cart description"]},"discount_settings":{"title":"DiscountSettings","type":"object","properties":{"custom_discounts_enabled":{"description":"This parameter enables custom discounts for a cart. When set to true and `use_rule_promotions` is not enabled, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).","type":"boolean","examples":[false]},"use_rule_promotions":{"description":"When set to true, this parameter allows the cart to use rule promotions. You can enable this setting together with `custom_discounts_enabled`, for example, while transitioning between promotion systems. However, an individual cart can only contain one type of discount at a time.","type":"boolean","examples":[false]}}},"inventory_settings":{"title":"InventorySettings","type":"object","properties":{"defer_inventory_check":{"description":"This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout","type":"boolean","examples":[false]}}},"item_settings":{"title":"ItemSettings","type":"object","properties":{"separate_items_by_location":{"description":"When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","examples":[false]}}},"name":{"description":"The cart name provided by the shopper. A cart name must contain 1 to 255 characters. You cannot use whitespace characters, but special characters are permitted. For more information, see the [Safe Characters](/guides/Getting-Started/safe-characters) section.","type":"string","examples":["my cart name"]},"contact":{"title":"CartContact","type":"object","properties":{"email":{"description":"The email address attached to a cart.","type":"string","format":"email","examples":["tester@email.com"]}}},"snapshot_date":{"description":"This optional parameter sets a reference date for the cart. If this parameter is set, it allows the cart to act as one that might occur on that specified date. For example, such future carts might acquire future-enabled discounts, allowing users to test and validate future interactions with carts. The snapshot_date must be in the format 2026-02-21T15:07:25Z. By default, this parameter is left empty.","type":"string","examples":["2026-09-10T00:12:00Z"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"payment_intent_id":{"description":"To remove the Stripe payment intent from a cart, pass the empty value in the `payment_intent_id` field.  You must use an empty value for this field. You cannot use this endpoint to directly update the cart to use an existing Payment Intent.","type":"string","examples":[""]}}}}},"examples":{"Create Cart":{"value":{"data":{"name":"Bob's cart","description":"For Holidays","discount_settings":{"custom_discounts_enabled":true}}}},"Create Preview Cart":{"value":{"data":{"name":"promotion preview cart","description":"preview promotions","snapshot_date":"2026-09-10T00:12:00Z"}}},"Create a Cart with Custom Attributes":{"value":{"data":{"name":"cart with custom attributes","description":"cart description","custom_attributes":{"affiliate_link":{"type":"string","value":"https://site.com?tag=influencer04-20"}}}}},"Create a Cart with Contact Email":{"value":{"data":{"name":"cart with contact email","description":"cart description","contact":{"email":"tester@email.com"}}}},"Create a Cart with Deferred Inventory Check":{"value":{"data":{"name":"cart with deferred inventory check","description":"cart description","inventory_settings":{"defer_inventory_check":true}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"CartResponse","allOf":[{"title":"BaseCartResponse","type":"object","properties":{"id":{"description":"The unique identifier for the cart. Use SDK or create it yourself.","type":"string"},"name":{"description":"The name of this cart.","type":"string","examples":["cart name"]},"description":{"description":"A description of the cart.","type":"string","examples":["cart description"]},"contact":{"title":"CartContact","type":"object","properties":{"email":{"description":"The email address attached to a cart.","type":"string","format":"email","examples":["tester@email.com"]}}},"discount_settings":{"title":"DiscountSettings","type":"object","properties":{"custom_discounts_enabled":{"description":"This parameter enables custom discounts for a cart. When set to true and `use_rule_promotions` is not enabled, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).","type":"boolean","examples":[false]},"use_rule_promotions":{"description":"When set to true, this parameter allows the cart to use rule promotions. You can enable this setting together with `custom_discounts_enabled`, for example, while transitioning between promotion systems. However, an individual cart can only contain one type of discount at a time.","type":"boolean","examples":[false]}}},"inventory_settings":{"title":"InventorySettings","type":"object","properties":{"defer_inventory_check":{"description":"This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout","type":"boolean","examples":[false]}}},"item_settings":{"title":"ItemSettings","type":"object","properties":{"separate_items_by_location":{"description":"When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","examples":[false]}}},"payment_intent_id":{"description":"Stripe-assigned unique identifier for the linked Payment Intent","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"snapshot_date":{"description":"The snapshot date for the cart.","type":"string","format":"date-time"},"links":{"type":"object","properties":{"self":{"description":"A link to that specific resource.","type":"string"}},"examples":["https://useast.api.elasticpath.com/v2/carts/1"]},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"}}}}}},"relationships":{"type":"object","properties":{"customers":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"items":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}]}},"required":["data"]}]},"accounts":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}}},{"type":"object","properties":{"type":{"description":"The type of object being returned.","type":"string","const":"cart"}}}]},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}},"meta":{"type":"object","description":"Additional metadata for the cart response.","properties":{"payment_intent":{"type":"object","description":"Payment intent details with nested structure including status and other Stripe payment intent fields","additionalProperties":true}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"CartEntityResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"403":{"description":"Unauthorized call","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Create an Account Cart Association

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Account Cart Association"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/relationships/accounts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can create associations between an account and one or more carts. After cart associations exist for an account, the account can access those carts across any device.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The ID for the cart created by the account. Ensure that you follow the guidelines for [Safe Characters](/guides/Getting-Started/safe-characters).","required":true,"style":"simple","schema":{"type":"string"}},{"name":"EP-Account-Management-Authentication-Token","in":"header","description":"An Account Management Authentication token to access a specific account's carts.","style":"simple","schema":{"type":"string","examples":["{{accountToken}}"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Carts Relationships Accounts Data","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The ID of the account.","type":"string","examples":["{{accountID}}"]},"type":{"description":"The type of related object. Ensure that it is account.","type":"string","examples":["account"]}}}}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","headers":{},"content":{"application/json":{"schema":{"allOf":[{"title":"Carts Relationships Accounts Data","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The ID of the account.","type":"string","examples":["{{accountID}}"]},"type":{"description":"The type of related object. Ensure that it is account.","type":"string","examples":["account"]}}}}}}]}}}},"204":{"description":"No Content is sent back in case the account has already been associated to the cart.","headers":{},"content":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Invalid Association","value":{"errors":[{"detail":"Unable to associate accounts to carts with contact emails attached.","status":400,"title":"Cannot associate accounts to carts with contact emails"}]}}}}}}}}}
>
  
</StatusCodes>

---

## Create Stripe Payment Intent for a Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Stripe Payment Intent for a Cart"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/payments"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The Cart Payment Intent feature enables the creation of a Stripe Payment Intent specifically tied to a shopping cart and its subsequent order. This allows Payment Intent users to track payment details from the cart stage and seamlessly maintain consistency in payment information throughout the order stage. Using these features, you can create Payment Intents for their carts, update Payment Intents with final cart details, and synchronize Payment Intents from Stripe to Commerce.

:::note

- Typically, in Commerce, inventory is allocated at the time of payment initiation after an order is created. However, in the case of Cart Payment Intent, information about the payment is received only upon synchronizing the order from Stripe to Commerce. This may happen after the payment is completed. Therefore, there might be a delay between the payment made and allocation, increasing the chance of paying for items that are not in stock.
- There are certain fields you can choose to set up when [creating a payment intent](https://stripe.com/docs/api/payment_intents/create). However, if you decide to update a payment intent, the available options may not be the same as those allowed while creating a payment intent. See [updating a payment intent](https://stripe.com/docs/api/payment_intents/update).

:::

The following steps outline the workflow associated with the Payment Intent:

1. [Add items to cart](/docs/api/carts/manage-carts#add-custom-item-to-cart).
1. [Create a Payment Intent for the cart](/docs/api/carts/create-cart-payment-intent). The Payment Intent is created in Stripe, reflecting the cart and transaction details, including currency, amounts, payment type, and any optional Stripe details. The Payment Intent ID is generated and linked to the cart.
1. [Update a Payment Intent](/docs/carts-orders/update-cart-payment-intent). This step is optional but becomes necessary when there are changes in the cart details at the time of payment. It ensures the Payment Intent accurately reflects the current cart details when processing the payments on the front end.
1. [Checkout the cart](/docs/api/carts/checkout). An unpaid order is created, and the Payment Intent ID is linked to the order.
1. [Confirm the order](/docs/carts-orders/confirm-an-order). This is important because after checkout, it is essential to confirm the Payment Intent and synchronize it with Commerce. This results in a corresponding transaction and change in order statuses in Commerce. Additionally, the Payment Intent ID is removed from the order once it is linked via the transaction.

### Best Practices

We recommend you follow these practices to maintain consistency and accuracy when using Cart Payment Intent.

- After checkout, we recommend clearing the shopping cart. You can achieve this using a [Delete a cart](/docs/api/carts/delete-a-cart) endpoint or [Update a cart](/docs/api/carts/update-a-cart) to remove the Payment Intent ID. This helps to avoid potential issues where subsequent checkouts for the same cart might unintentionally use the previous Stripe Payment Intent ID.
- If it is not reasonable to clear the cart immediately after checkout due to several subsequent, duplicate checkouts to the same cart, ensure that you only synchronize the Payment Intent when finalizing the order. Each order confirmation is unaware of the others, and syncing Payment Intent IDs for each confirmation can lead to duplicate transactions in Commerce. In other words, if you synchronize Payment Intents for earlier versions of a repeated checkout, you'll end up with multiple orders from the same cart, each having transactions linked to the same Payment Intent.
- To pay the entire amount at once, use the [Update Cart Payment Intent](/docs/carts-orders/update-cart-payment-intent) endpoint to update the Stripe Payment Intent with the final cart details when preparing to take the payment. Doing so, ensures that the Payment Intent accurately reflects the current cart details when processing payments on the front end. We do not recommend calling the [Update Cart Payment Intent](/docs/carts-orders/update-cart-payment-intent) for each individual change in the cart, as this can lead to more requests and may slow down the front-end performance.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","required":true,"style":"simple","schema":{"type":"string"},"description":"The universally unique identifier of the cart for which you want to create a payment intent."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":false,"content":{"application/json":{"schema":{"title":"Elastic Path Payments Powered By Stripe","type":"object","properties":{"data":{"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the gateway. You must use `elastic_path_payments_stripe`.","type":"string","const":"elastic_path_payments_stripe"},"options":{"type":"object","properties":{"receipt_email":{"description":"Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode.","type":"string"},"automatic_payment_methods":{"type":"object","description":"Parent object determining whether to use Stripe's `automatic_payment_methods` setting.","properties":{"enabled":{"type":"boolean","description":"When set to true, it displays all enabled payment methods from the Stripe dashboard. When set to false, the Stripe default, which is card, is used."}}}}},"payment_method_types":{"type":"array","items":{"type":"string"},"description":"Specifies the Stripe payment method types configured for the store. See [Stripe Documentation](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types).","examples":[["card"]]},"payment":{"description":"Specifies the Stripe token or source.","type":"string"}}}]}}},"examples":{"Create Stripe Payment Intent for a Cart":{"value":{"data":{"gateway":"elastic_path_payments_stripe","method":"purchase","options":{"automatic_payment_methods":{"enabled":true},"receipt_email":"john@example.com"}}}},"Create Stripe Payment Intent for a Cart Using Specific Payment Methods":{"value":{"data":{"gateway":"elastic_path_payments_stripe","method":"purchase","payment_method_types":["affirm","card","link"],"options":{"receipt_email":"john@example.com"}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Payment Intent created successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"CartResponse","allOf":[{"title":"BaseCartResponse","type":"object","properties":{"id":{"description":"The unique identifier for the cart. Use SDK or create it yourself.","type":"string"},"name":{"description":"The name of this cart.","type":"string","examples":["cart name"]},"description":{"description":"A description of the cart.","type":"string","examples":["cart description"]},"contact":{"title":"CartContact","type":"object","properties":{"email":{"description":"The email address attached to a cart.","type":"string","format":"email","examples":["tester@email.com"]}}},"discount_settings":{"title":"DiscountSettings","type":"object","properties":{"custom_discounts_enabled":{"description":"This parameter enables custom discounts for a cart. When set to true and `use_rule_promotions` is not enabled, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).","type":"boolean","examples":[false]},"use_rule_promotions":{"description":"When set to true, this parameter allows the cart to use rule promotions. You can enable this setting together with `custom_discounts_enabled`, for example, while transitioning between promotion systems. However, an individual cart can only contain one type of discount at a time.","type":"boolean","examples":[false]}}},"inventory_settings":{"title":"InventorySettings","type":"object","properties":{"defer_inventory_check":{"description":"This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout","type":"boolean","examples":[false]}}},"item_settings":{"title":"ItemSettings","type":"object","properties":{"separate_items_by_location":{"description":"When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","examples":[false]}}},"payment_intent_id":{"description":"Stripe-assigned unique identifier for the linked Payment Intent","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"snapshot_date":{"description":"The snapshot date for the cart.","type":"string","format":"date-time"},"links":{"type":"object","properties":{"self":{"description":"A link to that specific resource.","type":"string"}},"examples":["https://useast.api.elasticpath.com/v2/carts/1"]},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"}}}}}},"relationships":{"type":"object","properties":{"customers":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"items":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}]}},"required":["data"]}]},"accounts":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}}},{"type":"object","properties":{"type":{"description":"The type of object being returned.","type":"string","const":"cart"}}}]},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}},"meta":{"type":"object","description":"Additional metadata for the cart response.","properties":{"payment_intent":{"type":"object","description":"Payment intent details with nested structure including status and other Stripe payment intent fields","additionalProperties":true}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"CartEntityResponse"}}}}}}
>
  
</StatusCodes>

---

## Create a Customer Cart Association

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Customer Cart Association"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/relationships/customers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can create associations between a customer and one or more carts. After cart associations exist for a customer, the customer can access those carts across any device.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The ID for the cart created by the customer. Ensure that you follow the guidelines for [Safe Characters](/guides/Getting-Started/safe-characters).","required":true,"style":"simple","schema":{"type":"string"}},{"name":"X-Moltin-Customer-Token","in":"header","description":"A customer token to access a specific customer's carts.","style":"simple","schema":{"type":"string","examples":["{{customerToken}}"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Carts Relationships Customers Data","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string","examples":["{{customerID}}"]},"type":{"description":"The type of related object. Ensure that it is customer.","type":"string","examples":["customer"]}}}}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","headers":{},"content":{"application/json":{"schema":{"allOf":[{"title":"Carts Relationships Customers Data","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string","examples":["{{customerID}}"]},"type":{"description":"The type of related object. Ensure that it is customer.","type":"string","examples":["customer"]}}}}}}]}}}},"204":{"description":"No Content","headers":{},"content":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"422":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Invalid Association","value":{"errors":[{"detail":"Unable to associate customers to carts with contact emails attached.","status":400,"title":"Cannot associate customers to carts with contact emails"}]}}}}}}}}}
>
  
</StatusCodes>

---

## Create a shipping group for an order

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a shipping group for an order"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/orders/{orderID}/shipping-groups"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new shipping group for an order

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","required":true,"description":"The ID of the order","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"Shipping group details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["type"],"properties":{"type":{"type":"string","const":"shipping_group"},"shipping_type":{"type":"string","description":"The shipping type for this group"},"tracking_reference":{"type":"string","description":"Tracking reference for the shipment"},"address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"phone_number":{"type":"string"},"company_name":{"type":"string"},"line_1":{"type":"string"},"line_2":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"},"county":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"instructions":{"type":"string"}}},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Shipping group created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Shipping Group Response","type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"id":{"type":"string"},"relation":{"type":"string"},"cart_id":{"type":"string"},"order_id":{"type":"string"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","maxLength":64,"examples":["SG-12345"]},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"relationships":{"type":"object","properties":{"cart":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"order":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}},"discounts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"},"title":"Discounts"},"meta":{"type":"object","properties":{"shipping_display_price":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"base":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"fees":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"required":["total","base"],"title":"ShippingPriceResponse"},"total_display_price":{"description":"Order pricing information.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}},"required":["with_tax","without_tax","tax","discount","balance_owing","paid","authorized","without_discount","shipping","shipping_discount"],"title":"OrderPriceWrapperMeta"}},"title":"ShippingGroupMeta"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"status":400,"title":"Bad Request","detail":"Invalid request format"}]}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"status":404,"title":"Not Found","detail":"Order not found"}]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"status":422,"title":"Unprocessable Entity","detail":"Cannot create shipping group for this order"}]}}}}}}
>
  
</StatusCodes>

---

## Create a new shipping group for a cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a new shipping group for a cart"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/shipping-groups"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new shipping group for a cart

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","required":true,"description":"The ID of the cart","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters.","type":"string","maxLength":64},"shipping_price":{"type":"object","properties":{"total":{"type":"number"},"base":{"type":"number"},"tax":{"type":"number"},"fees":{"type":"number"},"discount":{"type":"number"}},"title":"ShippingPriceRequest"},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"includes_tax":{"type":"boolean"},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"}}}},"title":"CreateShippingGroupRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Shipping group created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Shipping Group Response","type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"id":{"type":"string"},"relation":{"type":"string"},"cart_id":{"type":"string"},"order_id":{"type":"string"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","maxLength":64,"examples":["SG-12345"]},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"relationships":{"type":"object","properties":{"cart":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"order":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}},"discounts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"},"title":"Discounts"},"meta":{"type":"object","properties":{"shipping_display_price":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"base":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"fees":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"required":["total","base"],"title":"ShippingPriceResponse"},"total_display_price":{"description":"Order pricing information.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}},"required":["with_tax","without_tax","tax","discount","balance_owing","paid","authorized","without_discount","shipping","shipping_discount"],"title":"OrderPriceWrapperMeta"}},"title":"ShippingGroupMeta"}}},"included":{"type":"object","description":"Related objects that are included in the response when using the include query parameter.","properties":{"items":{"description":"Array of order items associated with this shipping group.","type":"array","items":{"title":"OrderItemResponse","type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["68bf8510-bebf-47b1-96ba-8a9930c7d928"]},"quantity":{"description":"The quantity of this item were ordered.","type":"number","examples":[1]},"product_id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["4e9c6098-9701-4839-a69c-54d8256d9012"]},"subscription_offering_id":{"description":"The unique identifier for the subscription offering for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["69a39623-e681-415e-83c0-e1281010c77d"]},"name":{"description":"The name of this order item.","type":"string","examples":["Product 123"]},"sku":{"description":"The SKU code for the order item.","type":"string","examples":["IFD-1"]},"location":{"description":"The stock location for this order item.","type":"string","readOnly":true},"unit_price":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"value":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"discounts":{"type":"array","items":{"title":"DiscountData","type":"object","properties":{"amount":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"code":{"type":"string"},"id":{"type":"string","format":"uuid","readOnly":true},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}}}},"links":{"type":"object"},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discounts":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$1.00"]},"constituents":{"type":"object","description":"Detailed breakdown of discount constituents by ID","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","description":"The discount amount"},"currency":{"type":"string","description":"The currency code"},"formatted":{"type":"string","description":"The formatted discount amount"}}}}}}},"original_price":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"type":"object","properties":{"cart_item":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this item.","type":"string","format":"uuid","readOnly":true,"examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}},"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.","type":"string","examples":["default"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","examples":["pim","legacy"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Component product ID","type":"string"},"type":{"description":"Component product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product metadata as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price information as a generic object","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the bundle product.","type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"custom_inputs":{"description":"Custom inputs for the order item as a generic object","type":"object","additionalProperties":true},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true},"shipping_group_id":{"description":"The shipping group ID for the order item","type":"string"},"promotion_source":{"description":"The promotion source for the order item","type":"string"},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"subscription_configuration":{"description":"Subscription configuration for the order item","type":"object","properties":{"plan":{"description":"Subscription plan details","type":"string"},"pricing_option":{"description":"Pricing option for the subscription","type":"string"}}}}}}},"additionalProperties":false},"errors":{"type":"array","description":"Array of validation or processing errors","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"ShippingGroupEntityResponse"},"example":{"data":{"id":"96b1d104-0d2e-41fd-9543-6c3c5a698959","type":"shipping_group","relation":"cart","cart_id":"96b1d104-0d2e-41fd-9543-6c3c5a698959","shipping_type":"standard","tracking_reference":"TRACK123","address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"ACME Corp","line_1":"123 Main St","line_2":"Suite 100","city":"Portland","postcode":"97201","county":"Multnomah","country":"US","region":"Oregon","instructions":"Leave at front door"},"delivery_estimate":{"start":"2024-01-15T00:00:00Z","end":"2024-01-20T00:00:00Z"},"created_at":"2024-01-10T12:00:00Z","updated_at":"2024-01-10T12:00:00Z"}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"currency_mismatch":{"value":{"errors":[{"status":400,"title":"Cart Currency Mismatch","detail":"This cart uses USD, cannot add shipping group with currency EUR"}]}},"invalid_dates":{"value":{"errors":[{"status":400,"title":"Date Logic Discrepancy","detail":"The start date cannot occur after the end date"}]}}}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"status":404,"title":"Not Found","detail":"Cart not found"}]}}}}}}
>
  
</StatusCodes>

---

## Custom Discounts

With custom discounts, you can allow your shoppers to apply discounts from external services to their purchases. To apply custom discounts to carts and cart items, you need to set `custom_discounts_enabled` field to `true` in your [Cart Settings](/docs/api/carts/put-v-2-settings-cart).

You cannot add custom discounts to an empty cart.

:::caution

- You can apply up to five custom discounts to cart and cart item.
- The stores that use [simple calculation method](/guides/How-To/Carts/calculate-totals) do not support custom discounts.

:::

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Customer Cart Associations

You can create associations between a customer and one or more carts. After cart associations exist for a customer, those carts are accessible across any device. You can delete associations as required.

There are two ways to access the cart: with a customer token and without one.

### With a `customer` token

These endpoints are for users who authenticated implicitly and require a customer token in the header to access the customer cart associations APIs. For more information, see the [Customer Token](/docs/customer-management/customer-management-api/customer-tokens) documentation.

#### Cart creation

Shoppers create carts and can use any of the carts that they created to check out an order.

:::note

You can create a cart id, name, and description for the cart. The cart requires a name. Ensure that the string length is greater than or equal to one. Use any symbol in the name and description. For cart id, ensure that you follow the guidelines for safe characters. For more information about cart id naming requirements, see [Safe Characters](/guides/Getting-Started/safe-characters).

:::

### Without a `customer` token

These endpoints are for users who use the Client Credentials Token and do not require a Customer token in the header to access the customer cart associations APIs. For more information, see the [Authentication](/docs/authentication/security) documentation.

This user acts as a system administrator and can call any customer cart association operations for any customer and cart.

### Error Codes

You might encounter the following response codes, depending on the scenario:

* `400` - `The type does not exist or is not listed as customer` - Ensure that the type is `customer` and is present.

* `403` - `Cannot associate more than one customer`.

* `403` - `Customer does not have the required permissions to fulfill this request`.

* `403` - `Invalid json payload` - Check JSON input. The request body must be an array `[]`. If the request body is an object, the error is generated.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Delete a Cart Item

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Cart Item"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/items/{cartitemID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to delete a cart item.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart created by you.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"The unique identifier of the cart that you want to delete.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Cart Item Response","type":"object","properties":{"id":{"description":"The unique identifier for the cart item.","type":"string","format":"uuid","readOnly":true,"examples":["4649fbb3-b8ee-4883-82c9-49a3d5fbacf1"]},"type":{"description":"The type of cart item.","type":"string","readOnly":true,"enum":["cart_item","custom_item","subscription_item","promotion_item"],"examples":["cart_item"]},"product_id":{"description":"The unique ID of the product (for cart_item type).","type":"string","format":"uuid","readOnly":true,"examples":["55cda543-f9d7-42a4-b40a-665f2e4ff7c5"]},"promotion_id":{"description":"The unique ID of the promotion (for promotion_item type).","type":"string","format":"uuid","readOnly":true,"examples":["9993387e-93ab-468f-bba9-cf13882dc52d"]},"subscription_offering_id":{"description":"The unique ID of the subscription offering for subscription items.","type":"string","format":"uuid","readOnly":true,"examples":["9c13669e-29d7-42ea-bc95-1b32399adb9d"]},"name":{"description":"The name of this item","type":"string","readOnly":true,"examples":["shirt"]},"description":{"description":"A description of the cart item.","type":"string","readOnly":true,"examples":["T-shirt."]},"sku":{"description":"The SKU of the cart item.","type":"string","readOnly":true,"examples":["sample-sku"]},"slug":{"description":"The slug of the cart item.","type":"string","readOnly":true,"examples":["sample-product"]},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if catalog_source=pim is set.","type":"string","readOnly":true,"format":"uuid","examples":["11d3f9d2-c99b-472c-96c3-51842333daea"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","readOnly":true,"examples":["pim"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","readOnly":true,"properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Product ID","type":"string"},"type":{"description":"Product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product meta information as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the cart item for bundle products.","type":"object","readOnly":true,"additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"image":{"type":"object","readOnly":true,"properties":{"mime_type":{"description":"The MIME type for the uploaded file.","type":"string","readOnly":true,"examples":["image/png"]},"file_name":{"description":"The name of the image file that was uploaded.","type":"string","readOnly":true,"examples":["shirt-trans.png"]},"href":{"description":"The link to the image.","type":"string","readOnly":true,"examples":["https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/7cc08cbb-256e-4271-9b01-d03a9fac9f0a.png"]}}},"quantity":{"description":"The quantity of the cart item.","type":"integer","readOnly":true,"examples":[1]},"auto_add_quantity":{"description":"The quantity automatically added (for gift items).","type":"integer","readOnly":true},"manage_stock":{"description":"Whether or not the quantity of the item will be checked against inventory.","type":"boolean","readOnly":true,"examples":[true]},"unit_price":{"description":"The unit price of the item.","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"value":{"description":"The total price of the item (i.e., unit * quantity).","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"discounts":{"description":"Array of discounts applied to the cart item.","type":"array","readOnly":true,"items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"}},"custom_inputs":{"description":"Custom inputs for personalized products.","type":"object","readOnly":true,"additionalProperties":true,"examples":[{"tshirt_front":"John Doe","tshirt_back":"My Custom Text"}]},"subscription_configuration":{"description":"Configuration for subscription items.","type":"object","readOnly":true,"properties":{"plan":{"description":"The subscription plan ID.","type":"string"},"pricing_option":{"description":"The subscription pricing option ID.","type":"string"}}},"links":{"type":"object","readOnly":true,"properties":{"product":{"description":"A URL related to the resource.","type":"string","examples":["https://useast.api.elasticpath.com/products/9eda5ba0-4f4a-4074-8547-ccb05d1b5981"]},"subscription_offering":{"description":"A URL related to the subscription offering resource.","type":"string"}}},"meta":{"type":"object","readOnly":true,"properties":{"display_price":{"type":"object","properties":{"with_tax":{"description":"The amount of this item after discounts and taxes are applied.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_tax":{"description":"The amount of this item after discounts are applied and before taxes.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"tax":{"description":"The amount of taxes applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"discount":{"description":"The amount of the discount applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_discount":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"original_price":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."},"discounts":{"description":"Detailed discount information.","type":"object","additionalProperties":{"type":"object","required":["amount","currency","formatted"],"properties":{"amount":{"description":"The discount amount.","type":"integer","examples":[100]},"currency":{"description":"The currency code.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted discount amount.","type":"string","examples":["$1.00"]},"constituents":{"description":"The discount constituents.","type":"object","additionalProperties":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"description":"Relationships to other resources.","readOnly":true,"type":"object","properties":{"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"custom_discounts":{"description":"Related custom discounts.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"shipping_group_id":{"description":"The shipping group ID for this item.","type":"string","readOnly":true,"examples":["eb063818-939a-458f-97a4-2601c0c2b445"]},"promotion_source":{"description":"The source of the promotion (for promotion items).","type":"string","readOnly":true,"enum":["rule-promotion"],"examples":["rule-promotion"]},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"location":{"description":"The stock location for this item.","type":"string","readOnly":true,"examples":["warehouse-1"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true}}}},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"type":"object","properties":{"automatic":{"type":"boolean"},"description":{"type":"string"},"end":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"promotion_type":{"type":"string"},"promotion_source":{"type":"string","description":"The source of the promotion"},"start":{"type":"string","format":"date-time"},"type":{"type":"string","const":"promotion"}}}},"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}}}},"meta":{"type":"object","description":"Additional meta information about the cart items collection.","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"balance_owing":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"messages":{"type":"array","description":"Optional array of informational messages that provide feedback about operations performed on the cart items, such as promotions added or discounts applied. This field is only present when there are relevant messages to display.\n","items":{"type":"object","properties":{"source":{"type":"object","description":"Identifies the cart item that triggered this message","properties":{"type":{"type":"string","description":"The type of the source item"},"id":{"type":"string","description":"The unique identifier of the source item"},"code":{"type":"string","description":"The promotion code (present when source type is promotion)"}},"required":["type","id"]},"title":{"type":"string","description":"A short descriptive title for the message"},"description":{"type":"string","description":"A detailed description of the message"}},"required":["title","description"]}},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"},"auto_add":{"type":"boolean","description":"Whether this promotion should be automatically added"},"targets":{"description":"Array of promotion targets (alternative structure)","type":"array","items":{"type":"object","properties":{"cart_item_id":{"type":"string","description":"The cart item ID for this target"},"quantity":{"type":"integer","description":"The quantity for this target"},"skus":{"type":"array","description":"Array of SKU codes for this target","items":{"type":"string"}}}}}}}}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"required":["data"],"title":"CartItemCollectionResponse"}}}}}}
>
  
</StatusCodes>

---

## Delete a Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Cart"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can delete a cart, including the items, name, description, and remove all associations.

### Errors

The following error message is received when you attempt to delete a cart that is associated with a customer. Before deletion, ensure that the cart is disassociated.

```json
message: {
    errors: [
      {
        status: 400,
        title: 'Last cart',
        detail: 'This is the last cart associated with a customer and it cannot be deleted, try disassociating instead'
      }
    ]
  }
````

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart that you want to delete.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Delete a Promotion via Promotion Code

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Promotion via Promotion Code"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/discounts/{promoCode}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can remove promotion code from a cart if it was applied manually. This endpoint does not work if the promotion is applied automatically.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"Specifies the unique identifier of a cart created by you.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"promoCode","in":"path","description":"Specifies the promotion code to be deleted.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}}}}
>
  
</StatusCodes>

---

## Delete a Tax Item

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Tax Item"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/taxes/{taxitemID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to delete a tax item.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"The unique identifier of the cart item.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"taxitemID","in":"path","description":"The unique identifier of the tax item.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}}}}
>
  
</StatusCodes>

---

## Delete Account Cart Association

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Account Cart Association"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/relationships/accounts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can delete an association between an account and a cart.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The ID for the cart created by the account.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"EP-Account-Management-Authentication-Token","in":"header","description":"An Account Management Authentication token to access a specific account's carts.","style":"simple","schema":{"type":"string","examples":["{{accountToken}}"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Carts Relationships Accounts Data","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The ID of the account.","type":"string","examples":["{{accountID}}"]},"type":{"description":"The type of related object. Ensure that it is account.","type":"string","examples":["account"]}}}}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Delete all Cart Items

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete all Cart Items"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/items"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A shopper can clean up their cart, deleting custom items, promotions, and so on, while the empty cart remains available. The cart id, name, description, and any account or customer associations persist. The shopper can continue to add items to the cart.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart created by you.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Could not apply EP promotion with the given code","value":{"errors":[{"detail":"The cart is configured to use custom discounts","meta":{"code":"10_OFF"},"status":422,"title":"Could not apply EP promotion with the given code"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete Cart Shipping Group

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Cart Shipping Group"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartId}/shipping-groups/{shippingGroupId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a shipping group from a cart. You cannot delete a shipping group that is attached to cart items.
You must first remove the shipping group from all cart items before deleting the shipping group.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartId","in":"path","required":true,"description":"The ID of the cart","schema":{"type":"string"}},{"name":"shippingGroupId","in":"path","required":true,"description":"The ID of the shipping group to delete","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Successfully deleted the shipping group"},"400":{"description":"Cannot delete shipping group that is attached to cart items","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"status":400,"title":"Cannot delete shipping group","detail":"Cannot delete shipping groups attached to cart items. Please remove the shipping group from its cart items and try again."}]}}}},"404":{"description":"Cart or shipping group not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Delete Custom Discount From Cart Item

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Custom Discount From Cart Item"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/custom-discounts/{customdiscountID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to delete custom discount from cart item.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"Specifies the ID for the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"Specifies the ID for the cart item.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"customdiscountID","in":"path","description":"Specifies the ID for the custom discount to be deleted.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}}}}
>
  
</StatusCodes>

---

## Delete Custom Discount From Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Custom Discount From Cart"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/custom-discounts/{customdiscountID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to delete custom discount from cart.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"Specifies the unique ID for the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"customdiscountID","in":"path","description":"Specifies the ID for the custom discount to be deleted.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}}}}
>
  
</StatusCodes>

---

## Delete Customer Cart Association

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Customer Cart Association"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/relationships/customers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can delete an association between a customer and a cart.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The ID for the cart created by the customer.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"X-Moltin-Customer-Token","in":"header","description":"A customer token to access a specific customer's carts.","style":"simple","schema":{"type":"string","examples":["{{customerToken}}"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Carts Relationships Customers Data","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string","examples":["{{customerID}}"]},"type":{"description":"The type of related object. Ensure that it is customer.","type":"string","examples":["customer"]}}}}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{},"content":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Delete Tax Item from Bundle Component

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Tax Item from Bundle Component"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/components/{productID}/taxes/{taxitemID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to delete a tax item from a specific bundle component (component product) within a cart item.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"The unique identifier of the cart item.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"productID","in":"path","description":"The unique identifier of the component product within the bundle.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"taxitemID","in":"path","description":"The unique identifier of the tax item on the component product.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content","headers":{}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Cart"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/carts/{cartID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to retrieve a specific cart. If a cart ID does not exist, a new cart will be automatically created. If the cart is associated with shipping groups, calling this endpoint displays the associated shipping group IDs in the `relationships` section.

You can easily get a new or existing cart by providing the unique cart reference in the request. If the cart is associated with shipping groups, calling this endpoint displays the associated shipping group IDs in the relationships section.

:::note

- The default cart name is Cart. However, you can update the cart name as required. Ensure that the string length of the name is greater than or equal to one. Follow the safe character guidelines for name and description naming. For more information about cart ID naming requirements, see the [Safe Characters](/guides/Getting-Started/safe-characters) section.
- Outside of the JS-SDK, we don't handle creating cart references. You need to create your own.

:::

:::caution

An empty cart is returned for any carts that don't currently exist. For more information about the cart items object, see [Get Cart Items](/docs/api/carts/get-cart-items).

:::

### Query parameters

| Name      | Required | Type     | Description                                |
|:----------|:---------|:---------|:-------------------------------------------|
| `include` | Optional | `string` | Comma-delimited string of entities that can be included. The information included are `items`,`tax_items`, `custom_discounts`, or `promotions`. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier for this cart that you created.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"array","description":"A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).","example":"custom_discounts","items":{"type":"string","enum":["custom_discounts","promotions"]}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"CartResponse","allOf":[{"title":"BaseCartResponse","type":"object","properties":{"id":{"description":"The unique identifier for the cart. Use SDK or create it yourself.","type":"string"},"name":{"description":"The name of this cart.","type":"string","examples":["cart name"]},"description":{"description":"A description of the cart.","type":"string","examples":["cart description"]},"contact":{"title":"CartContact","type":"object","properties":{"email":{"description":"The email address attached to a cart.","type":"string","format":"email","examples":["tester@email.com"]}}},"discount_settings":{"title":"DiscountSettings","type":"object","properties":{"custom_discounts_enabled":{"description":"This parameter enables custom discounts for a cart. When set to true and `use_rule_promotions` is not enabled, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).","type":"boolean","examples":[false]},"use_rule_promotions":{"description":"When set to true, this parameter allows the cart to use rule promotions. You can enable this setting together with `custom_discounts_enabled`, for example, while transitioning between promotion systems. However, an individual cart can only contain one type of discount at a time.","type":"boolean","examples":[false]}}},"inventory_settings":{"title":"InventorySettings","type":"object","properties":{"defer_inventory_check":{"description":"This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout","type":"boolean","examples":[false]}}},"item_settings":{"title":"ItemSettings","type":"object","properties":{"separate_items_by_location":{"description":"When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","examples":[false]}}},"payment_intent_id":{"description":"Stripe-assigned unique identifier for the linked Payment Intent","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"snapshot_date":{"description":"The snapshot date for the cart.","type":"string","format":"date-time"},"links":{"type":"object","properties":{"self":{"description":"A link to that specific resource.","type":"string"}},"examples":["https://useast.api.elasticpath.com/v2/carts/1"]},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"}}}}}},"relationships":{"type":"object","properties":{"customers":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"items":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}]}},"required":["data"]}]},"accounts":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}}},{"type":"object","properties":{"type":{"description":"The type of object being returned.","type":"string","const":"cart"}}}]},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}},"meta":{"type":"object","description":"Additional metadata for the cart response.","properties":{"payment_intent":{"type":"object","description":"Payment intent details with nested structure including status and other Stripe payment intent fields","additionalProperties":true}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"CartEntityResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Transaction

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Transaction"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/orders/{orderID}/transactions/{transactionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a transaction

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The unique identifier of the order that you require transactions for.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"transactionID","in":"path","description":"The unique identifier of the transaction.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"type":"object","properties":{"data":{"title":"TransactionResponse","type":"object","properties":{"id":{"description":"The ID of the transaction.","type":"string","format":"uuid","readOnly":true},"reference":{"description":"The payment gateway reference.","type":"string","examples":["manual"]},"name":{"description":"A custom name associated with the payment method.","type":"string","examples":["payment method name"]},"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.","type":"string","examples":["custom reference"]},"gateway":{"description":"The name of the payment gateway used.","type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents","stripe_platform_account"]},"amount":{"description":"The amount for this transaction.","type":"number","examples":[10000]},"refunded_amount":{"description":"The refunded amount.","type":"number","examples":[0]},"currency":{"description":"The transaction currency.","type":"string","examples":["USD"]},"transaction_type":{"description":"The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`.","type":"string","enum":["purchase","authorize","capture","refund"]},"type":{"description":"The type of object being returned.","type":"string"},"status":{"description":"The status provided by the gateway for this transaction, such as `complete` or `failed`.","type":"string","examples":["complete"]},"payment_details":{"description":"Payment gateway specific details.","type":"object","properties":{"detailed_status":{"description":"Detailed status from the payment gateway.","type":"string"}}},"failure_details":{"description":"Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information.","title":"FailureDetails","type":"object","properties":{"code":{"description":"Machine-readable failure or error code from the payment gateway.","type":"string","examples":["2"]},"reason":{"description":"Human-readable failure reason or error message from the payment gateway.","type":"string","examples":["This transaction has been declined."]}}},"payment_intent":{"description":"Payment intent details.","type":"object","additionalProperties":true},"capture_mechanism":{"description":"The mechanism used for capturing the transaction.","type":"string","enum":["automatic","manual"]},"refund_mechanism":{"description":"The mechanism used for refunding the transaction.","type":"string","enum":["automatic","manual"]},"client_parameters":{"description":"Client-specific parameters for payment processing.","type":"object","properties":{"redirect_url":{"description":"URL to redirect the client after payment.","type":"string"},"secret":{"description":"Client secret for payment processing.","type":"string"},"token":{"description":"Client token for payment processing.","type":"string"}}},"next_actions":{"description":"Array of next actions for the transaction.","type":"array","items":{"type":"string"}},"relationships":{"type":"object","properties":{"order":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Represents the type of the object being returned. It is always `order`.","type":"string","examples":["order"]},"id":{"description":"The ID of the order.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}},"meta":{"type":"object","properties":{"display_price":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"display_refunded_amount":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}}}}}}]}}}}}}
>
  
</StatusCodes>

---

## Get an Order

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Order"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/orders/{orderID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to retrieve a specific order.

### Includes

You can include related resources with the order response by using the `include` query parameter.

| Name      | Required | Type     | Description |
|:----------|:---------|:---------|:------------|
| `include` | Optional | `string` | Comma-delimited string of entities that can be included. The included options are `items`, `tax_items`, `custom_discounts`, or `promotions`. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The ID of the order.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"include","in":"query","description":"Comma-delimited string of entities to include (items, tax_items, custom_discounts, promotions).","required":false,"style":"form","explode":false,"schema":{"type":"string","examples":["items","items,tax_items","items,tax_items,custom_discounts"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"title":"OrderEntityResponse","type":"object","properties":{"data":{"title":"OrderResponse","type":"object","properties":{"type":{"description":"Specifies the type of object being returned. You must use `order`.","type":"string","const":"order"},"order_number":{"description":"Specifies a user-managed, optional field used as an alternative to the existing `order_id`. If provided, the order-number will be sent to Authorize.net instead of the `order_id`, and will appear as the invoice number in Authorize.net transactions.","type":"string","examples":[1234]},"external_ref":{"description":"An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","examples":["e-123456789"]},"id":{"description":"Specifies the unique identifier of the order.","type":"string","format":"uuid","readOnly":true,"examples":["aa854b8f-5930-476d-951a-e9b9cfbdefb1"]},"status":{"description":"Specifies the status of the order, such as `incomplete`, `complete`, `processing`, or `cancelled`.","type":"string","enum":["complete","incomplete","cancelled","processing"]},"payment":{"description":"Specifies the status of the payment, such as `unpaid`, `authorized`, `paid`, or `refunded`.","type":"string","enum":["authorized","paid","unpaid","refunded","partially_paid","partially_authorized"]},"shipping":{"description":"Specifies the status of the shipment, such as `fulfilled` or `unfulfilled`.","type":"string","enum":["unfulfilled","fulfilled"]},"anonymized":{"description":"Specifies if the order is anonymized.","type":"boolean","examples":[false]},"payment_intent_id":{"description":"Stripe Payment Intent ID.  Please see Stripe's Payment Intent [documentation](https://docs.stripe.com/api/payment_intents) for more information on Payment Intents.","type":"string","examples":["pi_3MtwBwLkdIwHu7ix28a3tqPa"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"links":{"type":"object"},"meta":{"title":"OrderMeta","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this order was created.","type":"string"},"updated_at":{"description":"The date this order was last updated.","type":"string"},"fully_paid_at":{"description":"The date this order was fully paid. Only present for orders with payment status 'paid'.","type":"string"}},"title":"OrderTimestamps"},"display_price":{"description":"Order pricing information including amounts, tax, discounts, and payment details.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}}},"is_manual":{"description":"Specifies if the order was created manually.","type":"boolean"}}},"billing_address":{"title":"BillingAddress","description":"Billing address information. You must specify at least one of region (state/province) or county.\n","anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}],"examples":[{"first_name":"John","last_name":"Doe","company_name":"John Doe Enterprises","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB"}]},"contact":{"title":"Contact","type":"object","properties":{"email":{"description":"The email address of the contact.","type":"string","examples":["johndoe@email.com"]},"name":{"description":"The name of the contact.","type":"string","examples":["John Doe"]}}},"customer":{"title":"Customer","type":"object","properties":{"name":{"description":"The name of the customer.","type":"string","examples":["John Doe"]},"email":{"description":"The email address of the customer.","type":"string","format":"email","examples":["john.doe@example.com"]},"id":{"description":"The unique identifier of the customer.","type":"string","format":"uuid","examples":["e5a0d684-a4af-4919-a348-f66b0b4955e0"]}}},"shipping_address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"relationships":{"type":"object","properties":{"items":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"customer":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account_member":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"store":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}},"included":{"description":"Optional included data such as order items, tax items, custom discounts, and promotions.\n","type":"object","properties":{"items":{"description":"Array of order items included in the response.","type":"array","items":{"title":"OrderItemResponse","type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["68bf8510-bebf-47b1-96ba-8a9930c7d928"]},"quantity":{"description":"The quantity of this item were ordered.","type":"number","examples":[1]},"product_id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["4e9c6098-9701-4839-a69c-54d8256d9012"]},"subscription_offering_id":{"description":"The unique identifier for the subscription offering for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["69a39623-e681-415e-83c0-e1281010c77d"]},"name":{"description":"The name of this order item.","type":"string","examples":["Product 123"]},"sku":{"description":"The SKU code for the order item.","type":"string","examples":["IFD-1"]},"location":{"description":"The stock location for this order item.","type":"string","readOnly":true},"unit_price":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"value":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"discounts":{"type":"array","items":{"title":"DiscountData","type":"object","properties":{"amount":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"code":{"type":"string"},"id":{"type":"string","format":"uuid","readOnly":true},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}}}},"links":{"type":"object"},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discounts":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$1.00"]},"constituents":{"type":"object","description":"Detailed breakdown of discount constituents by ID","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","description":"The discount amount"},"currency":{"type":"string","description":"The currency code"},"formatted":{"type":"string","description":"The formatted discount amount"}}}}}}},"original_price":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"type":"object","properties":{"cart_item":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this item.","type":"string","format":"uuid","readOnly":true,"examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}},"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.","type":"string","examples":["default"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","examples":["pim","legacy"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Component product ID","type":"string"},"type":{"description":"Component product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product metadata as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price information as a generic object","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the bundle product.","type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"custom_inputs":{"description":"Custom inputs for the order item as a generic object","type":"object","additionalProperties":true},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true},"shipping_group_id":{"description":"The shipping group ID for the order item","type":"string"},"promotion_source":{"description":"The promotion source for the order item","type":"string"},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"subscription_configuration":{"description":"Subscription configuration for the order item","type":"object","properties":{"plan":{"description":"Subscription plan details","type":"string"},"pricing_option":{"description":"Pricing option for the subscription","type":"string"}}}}}},"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}},"custom_discounts":{"description":"Array of custom discounts included in the response.","type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"description":"Array of promotions included in the response.","type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Order not found","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Order not found\",\n      \"status\": \"404\",\n      \"title\": \"Not Found\"\n    }\n  ]\n}\n"}}}}}}}}
>
  
</StatusCodes>

---

## Get Cart Items

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Cart Items"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/carts/{cartID}/items"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to retrieve cart items. If the cart is associated with shipping groups, calling this endpoint displays the associated shipping group IDs.

You can use this endpoint to retrieve the breakdown of cart items by promotion ID. For example, if you have Promotions Standard item discount with code *sale2024*, Rule Promotions item discount with code *sale2024*, and Rule Promotions cart discount with code *sale2024*, the `discounts.constituents` field in the response example will show the breakdown of the same promotion code used in both Promotions Standard and Rule Promotions.

```json
"data": [
{
    "id": "98de010d-dd10-4fa5-a070-0b9bcdc72974",
    "type": "cart_item",
    "product_id": "5a4662d2-9a2b-4f6e-a215-2970db914b0c",
    "name": "sku1",
    "description": "sku1",
    "sku": "sku1",
    "slug": "sku1",
    "image": {
        "mime_type": "",
        "file_name": "",
        "href": ""
    },
    "quantity": 1,
    "manage_stock": false,
    "unit_price": {
        "amount": 10000,
        "currency": "USD",
        "includes_tax": false
    },
    "value": {
        "amount": 10000,
        "currency": "USD",
        "includes_tax": false
    },
    "discounts": [
        {
            "amount": {
                "amount": -2000,
                "currency": "USD",
                "includes_tax": false
            },
            "code": "sale2024",
            "id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
            "promotion_source": "rule-promotion",
            "is_cart_discount": true
        },
        {
            "amount": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "code": "sale2024",
            "id": "de19a043-a6da-4bde-b896-d17e16b77e25",
            "promotion_source": "rule-promotion"
        },
        {
            "amount": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "code": "sale2024",
            "id": "509295ee-2971-45b6-801e-95df09756989"
        },
        {
            "amount": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "code": "sale2024",
            "id": "ca79e606-7ecd-41ac-9478-af4c8c28c546",
            "promotion_source": "rule-promotion",
            "is_cart_discount": true
        }
    ],
    "links": {
        "product": "https://useast.api.elasticpath.com/v2/products/5a4662d2-9a2b-4f6e-a215-2970db914b0c"
    },
    "meta": {
        "display_price": {
            "with_tax": {
                "unit": {
                    "amount": 5000,
                    "currency": "USD",
                    "formatted": "$50.00"
                },
                "value": {
                    "amount": 5000,
                    "currency": "USD",
                    "formatted": "$50.00"
                }
            },
            "without_tax": {
                "unit": {
                    "amount": 5000,
                    "currency": "USD",
                    "formatted": "$50.00"
                },
                "value": {
                    "amount": 5000,
                    "currency": "USD",
                    "formatted": "$50.00"
                }
            },
            "tax": {
                "unit": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "value": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "discount": {
                "unit": {
                    "amount": -5000,
                    "currency": "USD",
                    "formatted": "-$50.00"
                },
                "value": {
                    "amount": -5000,
                    "currency": "USD",
                    "formatted": "-$50.00"
                }
            },
            "without_discount": {
                "unit": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                },
                "value": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                }
            },
            "discounts": {
                "sale2024": {
                    "amount": -5000,
                    "currency": "USD",
                    "formatted": "-$50.00",
                    "constituents": {
                        "509295ee-2971-45b6-801e-95df09756989": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "ca79e606-7ecd-41ac-9478-af4c8c28c546": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "de19a043-a6da-4bde-b896-d17e16b77e25": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "e4d929d5-f471-4317-9a86-a84a6c572b44": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        }
                    }
                }
            }
        },
        "timestamps": {
            "created_at": "2024-05-24T18:00:58Z",
            "updated_at": "2024-05-24T18:00:58Z"
        }
    },
    "catalog_id": "09b9359f-897f-407f-89a2-702e167fe781",
    "catalog_source": "pim"
}
```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart that you created.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"include","in":"query","description":"A comma-separated list of related resources to include in the response.","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["tax_items","custom_discounts","promotions"]}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Cart Item Response","type":"object","properties":{"id":{"description":"The unique identifier for the cart item.","type":"string","format":"uuid","readOnly":true,"examples":["4649fbb3-b8ee-4883-82c9-49a3d5fbacf1"]},"type":{"description":"The type of cart item.","type":"string","readOnly":true,"enum":["cart_item","custom_item","subscription_item","promotion_item"],"examples":["cart_item"]},"product_id":{"description":"The unique ID of the product (for cart_item type).","type":"string","format":"uuid","readOnly":true,"examples":["55cda543-f9d7-42a4-b40a-665f2e4ff7c5"]},"promotion_id":{"description":"The unique ID of the promotion (for promotion_item type).","type":"string","format":"uuid","readOnly":true,"examples":["9993387e-93ab-468f-bba9-cf13882dc52d"]},"subscription_offering_id":{"description":"The unique ID of the subscription offering for subscription items.","type":"string","format":"uuid","readOnly":true,"examples":["9c13669e-29d7-42ea-bc95-1b32399adb9d"]},"name":{"description":"The name of this item","type":"string","readOnly":true,"examples":["shirt"]},"description":{"description":"A description of the cart item.","type":"string","readOnly":true,"examples":["T-shirt."]},"sku":{"description":"The SKU of the cart item.","type":"string","readOnly":true,"examples":["sample-sku"]},"slug":{"description":"The slug of the cart item.","type":"string","readOnly":true,"examples":["sample-product"]},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if catalog_source=pim is set.","type":"string","readOnly":true,"format":"uuid","examples":["11d3f9d2-c99b-472c-96c3-51842333daea"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","readOnly":true,"examples":["pim"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","readOnly":true,"properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Product ID","type":"string"},"type":{"description":"Product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product meta information as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the cart item for bundle products.","type":"object","readOnly":true,"additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"image":{"type":"object","readOnly":true,"properties":{"mime_type":{"description":"The MIME type for the uploaded file.","type":"string","readOnly":true,"examples":["image/png"]},"file_name":{"description":"The name of the image file that was uploaded.","type":"string","readOnly":true,"examples":["shirt-trans.png"]},"href":{"description":"The link to the image.","type":"string","readOnly":true,"examples":["https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/7cc08cbb-256e-4271-9b01-d03a9fac9f0a.png"]}}},"quantity":{"description":"The quantity of the cart item.","type":"integer","readOnly":true,"examples":[1]},"auto_add_quantity":{"description":"The quantity automatically added (for gift items).","type":"integer","readOnly":true},"manage_stock":{"description":"Whether or not the quantity of the item will be checked against inventory.","type":"boolean","readOnly":true,"examples":[true]},"unit_price":{"description":"The unit price of the item.","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"value":{"description":"The total price of the item (i.e., unit * quantity).","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"discounts":{"description":"Array of discounts applied to the cart item.","type":"array","readOnly":true,"items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"}},"custom_inputs":{"description":"Custom inputs for personalized products.","type":"object","readOnly":true,"additionalProperties":true,"examples":[{"tshirt_front":"John Doe","tshirt_back":"My Custom Text"}]},"subscription_configuration":{"description":"Configuration for subscription items.","type":"object","readOnly":true,"properties":{"plan":{"description":"The subscription plan ID.","type":"string"},"pricing_option":{"description":"The subscription pricing option ID.","type":"string"}}},"links":{"type":"object","readOnly":true,"properties":{"product":{"description":"A URL related to the resource.","type":"string","examples":["https://useast.api.elasticpath.com/products/9eda5ba0-4f4a-4074-8547-ccb05d1b5981"]},"subscription_offering":{"description":"A URL related to the subscription offering resource.","type":"string"}}},"meta":{"type":"object","readOnly":true,"properties":{"display_price":{"type":"object","properties":{"with_tax":{"description":"The amount of this item after discounts and taxes are applied.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_tax":{"description":"The amount of this item after discounts are applied and before taxes.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"tax":{"description":"The amount of taxes applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"discount":{"description":"The amount of the discount applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_discount":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"original_price":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."},"discounts":{"description":"Detailed discount information.","type":"object","additionalProperties":{"type":"object","required":["amount","currency","formatted"],"properties":{"amount":{"description":"The discount amount.","type":"integer","examples":[100]},"currency":{"description":"The currency code.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted discount amount.","type":"string","examples":["$1.00"]},"constituents":{"description":"The discount constituents.","type":"object","additionalProperties":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"description":"Relationships to other resources.","readOnly":true,"type":"object","properties":{"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"custom_discounts":{"description":"Related custom discounts.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"shipping_group_id":{"description":"The shipping group ID for this item.","type":"string","readOnly":true,"examples":["eb063818-939a-458f-97a4-2601c0c2b445"]},"promotion_source":{"description":"The source of the promotion (for promotion items).","type":"string","readOnly":true,"enum":["rule-promotion"],"examples":["rule-promotion"]},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"location":{"description":"The stock location for this item.","type":"string","readOnly":true,"examples":["warehouse-1"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true}}}},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"type":"object","properties":{"automatic":{"type":"boolean"},"description":{"type":"string"},"end":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"promotion_type":{"type":"string"},"promotion_source":{"type":"string","description":"The source of the promotion"},"start":{"type":"string","format":"date-time"},"type":{"type":"string","const":"promotion"}}}},"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}}}},"meta":{"type":"object","description":"Additional meta information about the cart items collection.","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"balance_owing":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"messages":{"type":"array","description":"Optional array of informational messages that provide feedback about operations performed on the cart items, such as promotions added or discounts applied. This field is only present when there are relevant messages to display.\n","items":{"type":"object","properties":{"source":{"type":"object","description":"Identifies the cart item that triggered this message","properties":{"type":{"type":"string","description":"The type of the source item"},"id":{"type":"string","description":"The unique identifier of the source item"},"code":{"type":"string","description":"The promotion code (present when source type is promotion)"}},"required":["type","id"]},"title":{"type":"string","description":"A short descriptive title for the message"},"description":{"type":"string","description":"A detailed description of the message"}},"required":["title","description"]}},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"},"auto_add":{"type":"boolean","description":"Whether this promotion should be automatically added"},"targets":{"description":"Array of promotion targets (alternative structure)","type":"array","items":{"type":"object","properties":{"cart_item_id":{"type":"string","description":"The cart item ID for this target"},"quantity":{"type":"integer","description":"The quantity for this target"},"skus":{"type":"array","description":"Array of SKU codes for this target","items":{"type":"string"}}}}}}}}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"required":["data"],"title":"CartItemCollectionResponse"}}}}}}
>
  
</StatusCodes>

---

## Get Carts

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Carts"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/carts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of carts. The carts returned depend on the authentication method used:

| Authentication Method | Header | Returns |
| :--- | :--- | :--- |
| **Customer Token** | `X-Moltin-Customer-Token` | Carts for the specified customer. See [Customer Tokens](/docs/customer-management/customer-management-api/customer-tokens). |
| **Account Token** | `EP-Account-Management-Authentication-Token` | Carts for the specified account. See [Account Management Token](/docs/api/accounts/post-v-2-account-members-tokens). |
| **Client Credentials** | `Authorization: Bearer <token>` | All carts or only registered carts, controlled by the `show_all_carts` setting. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart). |

**Client Credentials Behavior:**
- When `show_all_carts` is `true`: Returns all carts in the store.
- When `show_all_carts` is `false`: Returns only registered carts (associated with customers or accounts).

**Sorting**

Carts are sorted in descending order by `updated_date`. For more information, see [Pagination](/guides/Getting-Started/pagination).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"EP-Account-Management-Authentication-Token","in":"header","description":"An Account Management Authentication token to access a specific account's carts.","style":"simple","schema":{"type":"string","examples":["{{accountToken}}"]}},{"name":"X-Moltin-Customer-Token","in":"header","description":"A customer token to access a specific customer's carts.","style":"simple","schema":{"type":"string","examples":["{{customerToken}}"]}},{"name":"include","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"array","description":"A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).","example":["custom_discounts"],"items":{"type":"string","const":"custom_discounts"}}},{"name":"page[limit]","in":"query","description":"The maximum number of records per page.","required":false,"style":"form","explode":true,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"style":"form","explode":true,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"filter","in":"query","description":"Filter expression for searching carts. For more information about filtering, see [Filtering](/guides/Getting-Started/filtering).\n\n:::note\nFiltering is only supported when using **client credentials** (admin) authentication. When using a **customer token** (`X-Moltin-Customer-Token`) or **account token** (`EP-Account-Management-Authentication-Token`), the `filter` parameter is ignored and all carts associated with the customer or account are returned.\n:::\n\n**Supported Fields:**\n- `account_ids`: Filter carts by associated account ID (UUID format)\n- `name`: Filter carts by cart name (case-insensitive)\n\n**Supported Operators:**\n- `contains(field,value)`: Contains value in array field\n- `ilike(field,value)`: Case-insensitive string matching\n\n**Examples:**\n- `contains(account_ids,\"c24e5698-3b54-491b-9225-559c7a9cf2b2\")` - Find carts associated with a specific account\n- `ilike(name,\"Shopping Cart\")` - Find carts with name matching \"Shopping Cart\" (case-insensitive)\n- `ilike(name,\"*cart*\")` - Find carts with names containing \"cart\" (wildcard search)\n\n**Combining Filters:**\nYou can combine multiple filters using the `:`, and `|` operator for and and or respectively:\n- `contains(account_ids,\"abc123\"):ilike(name,\"Holiday Cart\")` - Find carts matching both conditions\n- `contains(account_ids,\"abc123\")|ilike(name,\"Holiday Cart\")` - Find carts matching either condition.\n","required":false,"style":"form","explode":false,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"CartResponse","allOf":[{"title":"BaseCartResponse","type":"object","properties":{"id":{"description":"The unique identifier for the cart. Use SDK or create it yourself.","type":"string"},"name":{"description":"The name of this cart.","type":"string","examples":["cart name"]},"description":{"description":"A description of the cart.","type":"string","examples":["cart description"]},"contact":{"title":"CartContact","type":"object","properties":{"email":{"description":"The email address attached to a cart.","type":"string","format":"email","examples":["tester@email.com"]}}},"discount_settings":{"title":"DiscountSettings","type":"object","properties":{"custom_discounts_enabled":{"description":"This parameter enables custom discounts for a cart. When set to true and `use_rule_promotions` is not enabled, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).","type":"boolean","examples":[false]},"use_rule_promotions":{"description":"When set to true, this parameter allows the cart to use rule promotions. You can enable this setting together with `custom_discounts_enabled`, for example, while transitioning between promotion systems. However, an individual cart can only contain one type of discount at a time.","type":"boolean","examples":[false]}}},"inventory_settings":{"title":"InventorySettings","type":"object","properties":{"defer_inventory_check":{"description":"This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout","type":"boolean","examples":[false]}}},"item_settings":{"title":"ItemSettings","type":"object","properties":{"separate_items_by_location":{"description":"When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","examples":[false]}}},"payment_intent_id":{"description":"Stripe-assigned unique identifier for the linked Payment Intent","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"snapshot_date":{"description":"The snapshot date for the cart.","type":"string","format":"date-time"},"links":{"type":"object","properties":{"self":{"description":"A link to that specific resource.","type":"string"}},"examples":["https://useast.api.elasticpath.com/v2/carts/1"]},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"}}}}}},"relationships":{"type":"object","properties":{"customers":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"items":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}]}},"required":["data"]}]},"accounts":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}}},{"type":"object","properties":{"type":{"description":"The type of object being returned.","type":"string","const":"cart"}}}]}},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string"},"first":{"description":"Always the first page.","type":"string"},"last":{"description":"If there is only one page, it is `null`.","type":"string"},"next":{"description":"If there is only one page, it is `null`.","type":"string"},"prev":{"description":"if the user is on the first page, it is `null`.","type":"string"}},"title":"Response.PageLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"description":"The current page.","type":"integer"},"limit":{"description":"The maximum number of records per page for this response. You can set this value up to 100.","type":"integer"},"offset":{"description":"The current offset by number of records, not pages. Offset is zero-based.","type":"integer"},"total":{"description":"The total page count.","type":"integer"}},"title":"Response.PaginationPage"},"results":{"type":"object","properties":{"total":{"description":"The total page count.","type":"integer"}},"title":"Response.PaginationResults"}},"title":"Response.Meta.Carts"}},"required":["data"],"title":"CartCollectionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"403":{"description":"Unauthorized call","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Orders

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Orders"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/orders"}
  context={"endpoint"}
>
  
</MethodEndpoint>

This endpoint returns all orders with custom flow fields. The pagination offset is set to fetch a maximum of 10,000 orders. If the store has 10,000 orders, and you fetch the orders without using filters, an error is returned. Use a filter to view orders when the order is beyond the 10,000 mark.

:::note

- Pass the `X-Moltin-Customer-Token` header to limit orders to a specific customer. See [Customer Tokens](/docs/customer-management/customer-management-api/customer-tokens).
- Pass the `EP-Account-Management-Authentication-Token` header to limit orders to a specific account. See [Account Management Token](/docs/api/accounts/post-v-2-account-members-tokens).
- You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

:::

### Filtering

The following operators and attributes are available for filtering orders.

| Attribute | Type | Operator | Example |
| :--- | :--- | :--- | :--- |
| `status` | `string` | `eq` | `eq(status,complete)` |
| `payment` | `string` | `eq` | `eq(payment,paid)` |
| `shipping` | `string` | `eq` | `eq(shipping,unfulfilled)` |
| `name` (`customer.name`) | `string` | `eq` / `like` | `like(name,Brad*)` |
| `email` (`customer.email`) | `string` | `eq` / `like` | `like(email,*@elasticpath.com)` |
| `customer_id` | `string` | `eq` / `like` | `eq(customer_id, e5a0d684-a4af-4919-a348-f66b0b4955e0)` |
| `account_id` | `string` | `eq` / `like` | `eq(account_id,3d7200c9-a9bc-4085-9822-63e80fd94a09)` |
| `account_member_id` | `string` | `eq` / `like` | `eq(account_member_id,2a8a3a92-2ccd-4b2b-a7af-52d3896eaecb)` |
| `contact.name` | `string` | `eq` / `like` | `eq(name,John Doe)` |
| `contact.email` | `string` | `eq` / `like` | `eq(email,John Doe)` |
| `shipping_postcode` | `string` | `eq` / `like` | `like(shipping_postcode,117*)` |
| `billing_postcode` | `string` | `eq` / `like` | `like(billing_postcode,117*)` |
| `with_tax` | `integer` | `gt`/`ge`/`lt`/`le` | `ge(with_tax,10000)` |
| `without_tax` | `integer` | `gt`/`ge`/`lt`/`le` | `ge(without_tax,10000)` |
| `currency` | `string` | `eq` | `eq(currency,USD)` |
| `product_id` | `string` | `eq` | `eq(product_id,6837058c-ae42-46db-b3c6-7f01e0c34b40)` |
| `product_sku` | `string` | `eq` | `eq(product_sku,deck-shoe-001)` |
| `created_at` | `date` | `eq` / `gt` / `ge`/ `le` / `lt` | `gt(created_at,YYYY-MM-DD)` |
| `updated_at` | `date` | `eq` / `gt` / `ge`/ `le`/ `lt` | `lt(updated_at,YYYY-MM-DD)` |
| `external_ref` | `string` | `eq` / `like` | `like(external_ref, 16be*)` |
| `order_number` | `string` | `eq` / `like` | `like(order_number, 123*)` |
### Includes
You can include related resources with the order response by using the `include` query parameter.
| Name | Optional | Type | Description | |:-----|:---------|:-----|:------------| | `include` | Optional | `string` | Comma-delimited string of entities that can be included. The information included are `items`, `tax_items`, `custom_discounts`, or `promotions`. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"x-moltin-customer-token","in":"header","description":"A customer token to access a specific customer's orders.","style":"simple","schema":{"type":"string","examples":["{{customerToken}}"]}},{"name":"include","in":"query","description":"Comma-delimited string of entities to include (items, tax_items, custom_discounts, promotions).","required":false,"style":"form","explode":false,"schema":{"type":"string","examples":["items","items,tax_items","items,tax_items,custom_discounts"]}},{"name":"page[limit]","in":"query","description":"The maximum number of records per page.","required":false,"style":"form","explode":true,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"style":"form","explode":true,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"filter","in":"query","description":"Filter expression for searching orders. See filtering documentation for available operators and attributes.","required":false,"style":"form","explode":false,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"OrderResponse","type":"object","properties":{"type":{"description":"Specifies the type of object being returned. You must use `order`.","type":"string","const":"order"},"order_number":{"description":"Specifies a user-managed, optional field used as an alternative to the existing `order_id`. If provided, the order-number will be sent to Authorize.net instead of the `order_id`, and will appear as the invoice number in Authorize.net transactions.","type":"string","examples":[1234]},"external_ref":{"description":"An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","examples":["e-123456789"]},"id":{"description":"Specifies the unique identifier of the order.","type":"string","format":"uuid","readOnly":true,"examples":["aa854b8f-5930-476d-951a-e9b9cfbdefb1"]},"status":{"description":"Specifies the status of the order, such as `incomplete`, `complete`, `processing`, or `cancelled`.","type":"string","enum":["complete","incomplete","cancelled","processing"]},"payment":{"description":"Specifies the status of the payment, such as `unpaid`, `authorized`, `paid`, or `refunded`.","type":"string","enum":["authorized","paid","unpaid","refunded","partially_paid","partially_authorized"]},"shipping":{"description":"Specifies the status of the shipment, such as `fulfilled` or `unfulfilled`.","type":"string","enum":["unfulfilled","fulfilled"]},"anonymized":{"description":"Specifies if the order is anonymized.","type":"boolean","examples":[false]},"payment_intent_id":{"description":"Stripe Payment Intent ID.  Please see Stripe's Payment Intent [documentation](https://docs.stripe.com/api/payment_intents) for more information on Payment Intents.","type":"string","examples":["pi_3MtwBwLkdIwHu7ix28a3tqPa"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"links":{"type":"object"},"meta":{"title":"OrderMeta","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this order was created.","type":"string"},"updated_at":{"description":"The date this order was last updated.","type":"string"},"fully_paid_at":{"description":"The date this order was fully paid. Only present for orders with payment status 'paid'.","type":"string"}},"title":"OrderTimestamps"},"display_price":{"description":"Order pricing information including amounts, tax, discounts, and payment details.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}}},"is_manual":{"description":"Specifies if the order was created manually.","type":"boolean"}}},"billing_address":{"title":"BillingAddress","description":"Billing address information. You must specify at least one of region (state/province) or county.\n","anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}],"examples":[{"first_name":"John","last_name":"Doe","company_name":"John Doe Enterprises","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB"}]},"contact":{"title":"Contact","type":"object","properties":{"email":{"description":"The email address of the contact.","type":"string","examples":["johndoe@email.com"]},"name":{"description":"The name of the contact.","type":"string","examples":["John Doe"]}}},"customer":{"title":"Customer","type":"object","properties":{"name":{"description":"The name of the customer.","type":"string","examples":["John Doe"]},"email":{"description":"The email address of the customer.","type":"string","format":"email","examples":["john.doe@example.com"]},"id":{"description":"The unique identifier of the customer.","type":"string","format":"uuid","examples":["e5a0d684-a4af-4919-a348-f66b0b4955e0"]}}},"shipping_address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"relationships":{"type":"object","properties":{"items":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"customer":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account_member":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"store":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}}},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string"},"first":{"description":"Always the first page.","type":"string"},"last":{"description":"If there is only one page, it is `null`.","type":"string"},"next":{"description":"If there is only one page, it is `null`.","type":"string"},"prev":{"description":"if the user is on the first page, it is `null`.","type":"string"}},"title":"Response.PageLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"description":"The current page.","type":"integer"},"limit":{"description":"The maximum number of records per page for this response. You can set this value up to 100.","type":"integer"},"offset":{"description":"The current offset by number of records, not pages. Offset is zero-based.","type":"integer"},"total":{"description":"The total page count.","type":"integer"}},"title":"Response.PaginationPage"},"results":{"type":"object","properties":{"total":{"description":"The total page count.","type":"integer"}},"title":"Response.PaginationResults"}},"title":"Response.Meta.Orders"}},"title":"OrderCollectionResponse"}}}}}}
>
  
</StatusCodes>

---

## Get Order Items

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Order Items"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/orders/{orderID}/items"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to retrieve order items.

### Includes

You can include related resources with the order items response by using the `include` query parameter.

| Name      | Required | Type     | Description |
|:----------|:---------|:---------|:------------|
| `include` | Optional | `string` | Comma-delimited string of entities that can be included. The included options are `tax_items`, `custom_discounts`, or `promotions`. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The ID of the order.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"include","in":"query","description":"Comma-delimited string of entities to include (tax_items, custom_discounts, promotions).","required":false,"style":"form","explode":false,"schema":{"type":"string","examples":["tax_items","tax_items,custom_discounts","tax_items,custom_discounts,promotions"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"OrderItemResponse","type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["68bf8510-bebf-47b1-96ba-8a9930c7d928"]},"quantity":{"description":"The quantity of this item were ordered.","type":"number","examples":[1]},"product_id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["4e9c6098-9701-4839-a69c-54d8256d9012"]},"subscription_offering_id":{"description":"The unique identifier for the subscription offering for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["69a39623-e681-415e-83c0-e1281010c77d"]},"name":{"description":"The name of this order item.","type":"string","examples":["Product 123"]},"sku":{"description":"The SKU code for the order item.","type":"string","examples":["IFD-1"]},"location":{"description":"The stock location for this order item.","type":"string","readOnly":true},"unit_price":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"value":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"discounts":{"type":"array","items":{"title":"DiscountData","type":"object","properties":{"amount":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"code":{"type":"string"},"id":{"type":"string","format":"uuid","readOnly":true},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}}}},"links":{"type":"object"},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discounts":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$1.00"]},"constituents":{"type":"object","description":"Detailed breakdown of discount constituents by ID","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","description":"The discount amount"},"currency":{"type":"string","description":"The currency code"},"formatted":{"type":"string","description":"The formatted discount amount"}}}}}}},"original_price":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"type":"object","properties":{"cart_item":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this item.","type":"string","format":"uuid","readOnly":true,"examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}},"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.","type":"string","examples":["default"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","examples":["pim","legacy"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Component product ID","type":"string"},"type":{"description":"Component product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product metadata as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price information as a generic object","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the bundle product.","type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"custom_inputs":{"description":"Custom inputs for the order item as a generic object","type":"object","additionalProperties":true},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true},"shipping_group_id":{"description":"The shipping group ID for the order item","type":"string"},"promotion_source":{"description":"The promotion source for the order item","type":"string"},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"subscription_configuration":{"description":"Subscription configuration for the order item","type":"object","properties":{"plan":{"description":"Subscription plan details","type":"string"},"pricing_option":{"description":"Pricing option for the subscription","type":"string"}}}}}},"included":{"description":"Optional included data such as tax items, custom discounts, and promotions.\n","type":"object","properties":{"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}},"custom_discounts":{"description":"Array of custom discounts included in the response.","type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"description":"Array of promotions included in the response.","type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}}},"title":"OrderItemCollectionResponse"}}}}}}
>
  
</StatusCodes>

---

## Retrieve all shipping groups for an order

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retrieve all shipping groups for an order"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/orders/{orderID}/shipping-groups"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve all shipping groups for an order

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","required":true,"description":"The ID of the order","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A list of shipping groups","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Shipping Group Response","type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"id":{"type":"string"},"relation":{"type":"string"},"cart_id":{"type":"string"},"order_id":{"type":"string"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","maxLength":64,"examples":["SG-12345"]},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"relationships":{"type":"object","properties":{"cart":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"order":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}},"discounts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"},"title":"Discounts"},"meta":{"type":"object","properties":{"shipping_display_price":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"base":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"fees":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"required":["total","base"],"title":"ShippingPriceResponse"},"total_display_price":{"description":"Order pricing information.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}},"required":["with_tax","without_tax","tax","discount","balance_owing","paid","authorized","without_discount","shipping","shipping_discount"],"title":"OrderPriceWrapperMeta"}},"title":"ShippingGroupMeta"}}}}}},"example":{"data":[{"id":"96b1d104-0d2e-41fd-9543-6c3c5a698959","type":"shipping_group","relation":"order","order_id":"96b1d104-0d2e-41fd-9543-6c3c5a698959","shipping_type":"standard","tracking_reference":"TRACK123","meta":{"shipping_display_price":{"total":{"amount":1000,"currency":"USD","formatted":"$10.00"},"base":{"amount":800,"currency":"USD","formatted":"$8.00"},"tax":{"amount":200,"currency":"USD","formatted":"$2.00"},"fees":{"amount":0,"currency":"USD","formatted":"$0.00"}}},"address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"ACME Corp","line_1":"123 Main St","line_2":"Suite 100","city":"Portland","postcode":"97201","county":"Multnomah","country":"US","region":"Oregon","instructions":"Leave at front door"},"delivery_estimate":{"start":"2024-01-15T00:00:00Z","end":"2024-01-20T00:00:00Z"}}]}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"status":404,"title":"Not Found","detail":"Order not found"}]}}}}}}
>
  
</StatusCodes>

---

## Get Order Transactions

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Order Transactions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/orders/{orderID}/transactions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get order transactions

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The unique identifier of the order.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"TransactionResponse","type":"object","properties":{"id":{"description":"The ID of the transaction.","type":"string","format":"uuid","readOnly":true},"reference":{"description":"The payment gateway reference.","type":"string","examples":["manual"]},"name":{"description":"A custom name associated with the payment method.","type":"string","examples":["payment method name"]},"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.","type":"string","examples":["custom reference"]},"gateway":{"description":"The name of the payment gateway used.","type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents","stripe_platform_account"]},"amount":{"description":"The amount for this transaction.","type":"number","examples":[10000]},"refunded_amount":{"description":"The refunded amount.","type":"number","examples":[0]},"currency":{"description":"The transaction currency.","type":"string","examples":["USD"]},"transaction_type":{"description":"The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`.","type":"string","enum":["purchase","authorize","capture","refund"]},"type":{"description":"The type of object being returned.","type":"string"},"status":{"description":"The status provided by the gateway for this transaction, such as `complete` or `failed`.","type":"string","examples":["complete"]},"payment_details":{"description":"Payment gateway specific details.","type":"object","properties":{"detailed_status":{"description":"Detailed status from the payment gateway.","type":"string"}}},"failure_details":{"description":"Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information.","title":"FailureDetails","type":"object","properties":{"code":{"description":"Machine-readable failure or error code from the payment gateway.","type":"string","examples":["2"]},"reason":{"description":"Human-readable failure reason or error message from the payment gateway.","type":"string","examples":["This transaction has been declined."]}}},"payment_intent":{"description":"Payment intent details.","type":"object","additionalProperties":true},"capture_mechanism":{"description":"The mechanism used for capturing the transaction.","type":"string","enum":["automatic","manual"]},"refund_mechanism":{"description":"The mechanism used for refunding the transaction.","type":"string","enum":["automatic","manual"]},"client_parameters":{"description":"Client-specific parameters for payment processing.","type":"object","properties":{"redirect_url":{"description":"URL to redirect the client after payment.","type":"string"},"secret":{"description":"Client secret for payment processing.","type":"string"},"token":{"description":"Client token for payment processing.","type":"string"}}},"next_actions":{"description":"Array of next actions for the transaction.","type":"array","items":{"type":"string"}},"relationships":{"type":"object","properties":{"order":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Represents the type of the object being returned. It is always `order`.","type":"string","examples":["order"]},"id":{"description":"The ID of the order.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}},"meta":{"type":"object","properties":{"display_price":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"display_refunded_amount":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}}}}}},"required":["data"],"title":"TransactionListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Request could not be processed\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}}}}}
>
  
</StatusCodes>

---

## Retrieve a specific shipping group for a cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retrieve a specific shipping group for a cart"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/carts/{cartId}/shipping-groups/{shippingGroupId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve a specific shipping group for a cart

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartId","in":"path","required":true,"description":"The ID of the cart","schema":{"type":"string"}},{"name":"shippingGroupId","in":"path","required":true,"description":"The ID of the shipping group","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Shipping group details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Shipping Group Response","type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"id":{"type":"string"},"relation":{"type":"string"},"cart_id":{"type":"string"},"order_id":{"type":"string"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","maxLength":64,"examples":["SG-12345"]},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"relationships":{"type":"object","properties":{"cart":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"order":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}},"discounts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"},"title":"Discounts"},"meta":{"type":"object","properties":{"shipping_display_price":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"base":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"fees":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"required":["total","base"],"title":"ShippingPriceResponse"},"total_display_price":{"description":"Order pricing information.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}},"required":["with_tax","without_tax","tax","discount","balance_owing","paid","authorized","without_discount","shipping","shipping_discount"],"title":"OrderPriceWrapperMeta"}},"title":"ShippingGroupMeta"}}}}},"example":{"data":{"id":"7cfa5b07-092e-4dbe-bbad-55a771a34117","type":"shipping_group","relation":"cart","cart_id":"96b1d104-0d2e-41fd-9543-6c3c5a698959","shipping_type":"standard","tracking_reference":"TRACK123","address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"ACME Corp","line_1":"123 Main St","line_2":"Suite 100","city":"Portland","postcode":"97201","county":"Multnomah","country":"US","region":"Oregon","instructions":"Leave at front door"},"delivery_estimate":{"start":"2024-01-15T00:00:00Z","end":"2024-01-20T00:00:00Z"},"meta":{"shipping_display_price":{"total":{"amount":1000,"currency":"USD","formatted":"$10.00"},"base":{"amount":800,"currency":"USD","formatted":"$8.00"},"tax":{"amount":200,"currency":"USD","formatted":"$2.00"},"fees":{"amount":0,"currency":"USD","formatted":"$0.00"}}}}}}}},"404":{"description":"Shipping group or cart not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"cart_not_found":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"Cart not found"}]}},"shipping_group_not_found":{"value":{"errors":[{"status":404,"title":"Cart shipping group not found","detail":"Cart shipping group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for cart [abc123]"}]}}}}}}}}
>
  
</StatusCodes>

---

## Retrieve a specific shipping group for an order

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retrieve a specific shipping group for an order"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/orders/{orderID}/shipping-groups/{shippingGroupID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve a specific shipping group for an order

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","required":true,"description":"The ID of the order","schema":{"type":"string"}},{"name":"shippingGroupID","in":"path","required":true,"description":"The ID of the shipping group","schema":{"type":"string"}},{"name":"include","in":"query","description":"A comma-separated list of related resources to include in the response.","required":false,"style":"form","explode":false,"schema":{"type":"string","const":"items"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Shipping group details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Shipping Group Response","type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"id":{"type":"string"},"relation":{"type":"string"},"cart_id":{"type":"string"},"order_id":{"type":"string"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","maxLength":64,"examples":["SG-12345"]},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"relationships":{"type":"object","properties":{"cart":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"order":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}},"discounts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"},"title":"Discounts"},"meta":{"type":"object","properties":{"shipping_display_price":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"base":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"fees":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"required":["total","base"],"title":"ShippingPriceResponse"},"total_display_price":{"description":"Order pricing information.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}},"required":["with_tax","without_tax","tax","discount","balance_owing","paid","authorized","without_discount","shipping","shipping_discount"],"title":"OrderPriceWrapperMeta"}},"title":"ShippingGroupMeta"}}},"included":{"type":"object","description":"Related objects that are included in the response when using the include query parameter.","properties":{"items":{"description":"Array of order items associated with this shipping group.","type":"array","items":{"title":"OrderItemResponse","type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["68bf8510-bebf-47b1-96ba-8a9930c7d928"]},"quantity":{"description":"The quantity of this item were ordered.","type":"number","examples":[1]},"product_id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["4e9c6098-9701-4839-a69c-54d8256d9012"]},"subscription_offering_id":{"description":"The unique identifier for the subscription offering for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["69a39623-e681-415e-83c0-e1281010c77d"]},"name":{"description":"The name of this order item.","type":"string","examples":["Product 123"]},"sku":{"description":"The SKU code for the order item.","type":"string","examples":["IFD-1"]},"location":{"description":"The stock location for this order item.","type":"string","readOnly":true},"unit_price":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"value":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"discounts":{"type":"array","items":{"title":"DiscountData","type":"object","properties":{"amount":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"code":{"type":"string"},"id":{"type":"string","format":"uuid","readOnly":true},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}}}},"links":{"type":"object"},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discounts":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$1.00"]},"constituents":{"type":"object","description":"Detailed breakdown of discount constituents by ID","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","description":"The discount amount"},"currency":{"type":"string","description":"The currency code"},"formatted":{"type":"string","description":"The formatted discount amount"}}}}}}},"original_price":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"type":"object","properties":{"cart_item":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this item.","type":"string","format":"uuid","readOnly":true,"examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}},"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.","type":"string","examples":["default"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","examples":["pim","legacy"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Component product ID","type":"string"},"type":{"description":"Component product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product metadata as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price information as a generic object","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the bundle product.","type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"custom_inputs":{"description":"Custom inputs for the order item as a generic object","type":"object","additionalProperties":true},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true},"shipping_group_id":{"description":"The shipping group ID for the order item","type":"string"},"promotion_source":{"description":"The promotion source for the order item","type":"string"},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"subscription_configuration":{"description":"Subscription configuration for the order item","type":"object","properties":{"plan":{"description":"Subscription plan details","type":"string"},"pricing_option":{"description":"Pricing option for the subscription","type":"string"}}}}}}},"additionalProperties":false},"errors":{"type":"array","description":"Array of validation or processing errors","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"ShippingGroupEntityResponse"},"example":{"data":{"id":"7cfa5b07-092e-4dbe-bbad-55a771a34117","type":"shipping_group","relation":"order","order_id":"96b1d104-0d2e-41fd-9543-6c3c5a698959","shipping_type":"standard","tracking_reference":"TRACK123","address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"ACME Corp","line_1":"123 Main St","line_2":"Suite 100","city":"Portland","postcode":"97201","county":"Multnomah","country":"US","region":"Oregon","instructions":"Leave at front door"},"delivery_estimate":{"start":"2024-01-15T00:00:00Z","end":"2024-01-20T00:00:00Z"},"meta":{"shipping_display_price":{"total":{"amount":1000,"currency":"USD","formatted":"$10.00"},"base":{"amount":800,"currency":"USD","formatted":"$8.00"},"tax":{"amount":200,"currency":"USD","formatted":"$2.00"},"fees":{"amount":0,"currency":"USD","formatted":"$0.00"}}}}}}}},"404":{"description":"Shipping group or order not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"order_not_found":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"Order not found"}]}},"shipping_group_not_found":{"value":{"errors":[{"status":404,"title":"Group not found","detail":"Group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for order [abc123]"}]}}}}}}}}
>
  
</StatusCodes>

---

## Retrieve all shipping groups for a cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retrieve all shipping groups for a cart"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/carts/{cartID}/shipping-groups"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve all shipping groups for a cart

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","required":true,"description":"The ID of the cart","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A list of shipping groups","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Shipping Group Response","type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"id":{"type":"string"},"relation":{"type":"string"},"cart_id":{"type":"string"},"order_id":{"type":"string"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","maxLength":64,"examples":["SG-12345"]},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"relationships":{"type":"object","properties":{"cart":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"order":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}},"discounts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"},"title":"Discounts"},"meta":{"type":"object","properties":{"shipping_display_price":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"base":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"fees":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"required":["total","base"],"title":"ShippingPriceResponse"},"total_display_price":{"description":"Order pricing information.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}},"required":["with_tax","without_tax","tax","discount","balance_owing","paid","authorized","without_discount","shipping","shipping_discount"],"title":"OrderPriceWrapperMeta"}},"title":"ShippingGroupMeta"}}}}}},"examples":{"Retrieve Shipping Groups for a Cart":{"value":{"data":[{"id":"96b1d104-0d2e-41fd-9543-6c3c5a698959","type":"shipping_group","relation":"cart","cart_id":"96b1d104-0d2e-41fd-9543-6c3c5a698959","shipping_type":"standard","tracking_reference":"TRACK123","meta":{"shipping_display_price":{"total":{"amount":1000,"currency":"USD","formatted":"$10.00"},"base":{"amount":800,"currency":"USD","formatted":"$8.00"},"tax":{"amount":200,"currency":"USD","formatted":"$2.00"},"fees":{"amount":0,"currency":"USD","formatted":"$0.00"}}},"address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"ACME Corp","line_1":"123 Main St","line_2":"Suite 100","city":"Portland","postcode":"97201","county":"Multnomah","country":"US","region":"Oregon","instructions":"Leave at front door"},"delivery_estimate":{"start":"2024-01-15T00:00:00Z","end":"2024-01-20T00:00:00Z"}}]}}}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get Cart Settings by Store ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Cart Settings by Store ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/cart/{storeID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves cart settings for the specified store.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"storeID","in":"path","description":"The store ID.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you're sending. Set this value to `settings`.","example":"settings"},"id":{"type":"string","description":"The unique identifier for the cart settings.","readOnly":true,"example":"15419118-44ce-5343-8ff6-574daf52bc6b"},"cart_expiry_days":{"type":"integer","description":"Indicates the number of days before a cart expires.","example":25},"discounts":{"type":"object","properties":{"custom_discounts_enabled":{"description":"When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false},"use_rule_promotions":{"description":"When set to `true`, this parameter allows the cart to use rule promotions.","type":"boolean","example":false}}},"inventories":{"type":"object","properties":{"defer_inventory_check":{"description":"When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false}}},"items":{"type":"object","properties":{"separate_items_by_location":{"description":"When `true`, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When `false` (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","example":false}}},"show_all_carts":{"description":"When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts).\n\nFor new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility.\n","type":"boolean","example":true}},"required":["type"]}},"title":"SettingsCart"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get Cart Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Cart Settings"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/cart"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves cart settings.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you're sending. Set this value to `settings`.","example":"settings"},"id":{"type":"string","description":"The unique identifier for the cart settings.","readOnly":true,"example":"15419118-44ce-5343-8ff6-574daf52bc6b"},"cart_expiry_days":{"type":"integer","description":"Indicates the number of days before a cart expires.","example":25},"discounts":{"type":"object","properties":{"custom_discounts_enabled":{"description":"When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false},"use_rule_promotions":{"description":"When set to `true`, this parameter allows the cart to use rule promotions.","type":"boolean","example":false}}},"inventories":{"type":"object","properties":{"defer_inventory_check":{"description":"When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false}}},"items":{"type":"object","properties":{"separate_items_by_location":{"description":"When `true`, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When `false` (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","example":false}}},"show_all_carts":{"description":"When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts).\n\nFor new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility.\n","type":"boolean","example":true}},"required":["type"]}},"title":"SettingsCart"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Add Items to Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Add Items to Cart"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/carts/{cartID}/items"}
  context={"endpoint"}
>
  
</MethodEndpoint>

### Add Product to Cart

Adding a Product to Cart is the most common Cart action. If you want to add any custom products or promotions, you need to do that as a separate action.

#### Dynamic Bundles

A bundle is a purchasable product that is composed of a combination of two or more products that you want to sell together. You can create multiple components within a bundle. Each component can have one or more options. Each option is a product and a quantity. You can configure minimum and/or maximum values for the number of product options in a component that your shoppers can select. For example, you can enable a shopper to select 1 or more product options from a list of 10. These are called [dynamic bundles](/docs/api/pxm/products/products#dynamic-bundles).

Your dynamic bundles are displayed in your published catalogs.

1. Use the configure a shopper endpoint to allow shoppers to make their selections from a bundle.
2. In the response of the configure a shopper, the `bundle_configuration` object contains the bundle selections a shopper has made.
3. In the add a product to cart request, use the `bundle_configuration` object to add the customers selections to a cart.

```json
  "bundle_configuration": {
       "selected_options": {
           "games": {
               "d7b79eb8-19d8-45ea-86ed-2324a604dd9c": 1
           },
           "toys": {
               "0192ccdd-6d33-4898-87d7-c4d87f2bf8ea": 1,
               "1aea6f97-f0d9-452c-b3c1-7fb5629ead82": 1
           }
       }
}
```

When a cart is checked out, the options a shopper selected are added to the order. See [order items](/docs/api/carts/get-order-items).

#### Personalized Products

You can allow shoppers to personalize their goods by adding custom text inputs to products directly. This feature is particularly useful for customizable items, such as personalized T-shirts or greeting cards. You can use this functionality by leveraging the `custom_inputs` attribute, and defining the details and validation rules for the custom text.

First, you must configure a `custom_inputs` attribute when creating a new product or updating an existing product. Once you have defined your custom inputs on a product, you must configure the custom inputs in your orders.

For example, you may sell T-shirts that can have personalized text on the front and back of the shirt.

```json
    {
      "data": {
        "type": "product",
          "attributes": {
              "custom_inputs": {
                  "front": {
                      "name": "T-Shirt Front",
                      "validation_rules": [
                      {
                          "type": "string",
                          "options": {
                          "max_length": 50
                      }
                  }
              ],
                    "required": false
        },
                  "back": {
                    "name": "T-Shirt Back",
                    "validation_rules": [
                {
                      "type": "string",
                      "options": {
                      "max_length": 50
            }
          }
        ],
                   "required": false
        }
      }
    }
  }
}
```

If the same product has different `custom_inputs` attributes, then these are added as separate items in a cart.

The `custom_inputs` attribute is stored in the cart item and the text for `custom_input` must not exceed 255 characters in length. When a cart is checked out, the `custom_inputs` attribute becomes part of the order.

#### Limitations on Usage of `custom_inputs` with Specific Promotion Types

When you add products to a cart with `custom_inputs`, there are certain limitations on usage of the `custom_inputs` with the following promotion types:

  - For [Free Gift Promotions](/docs/api/promotions/create-a-promotion), you can add `custom_inputs` to gift items.
  - For [Fixed Bundle Discount Promotions](/docs/api/promotions/create-a-promotion), the promotion applies as long as the cart contains the bundle SKUs even when there are different `custom_inputs`.
  - For [X for Y Discount Promotion and X for amount discount promotion](/docs/api/promotions/create-a-promotion), the promotion applies when there are two SKUs with the same `custom_inputs`. The promotion does not apply when there are different `custom_inputs` and the SKUs are in different line items.

#### Stock locations

When adding to a cart it is possible to specify which [stock location](/docs/api/pxm/inventory_mli/inventories-introduction?#multi-location-inventories) should be used for tracking inventory for that product by specifying its slug in `location`. This might represent the warehouse a product is shipped from or the store holding the stock in a Buy Online Pick Up In Store scenario.

Each line item is restricted to a single stock location. If the same product is added with a different location then the most recently-specified location will be used for the total quantity of that line item.

:::note

- Any requests to add a product to cart returns the collection of cart items.
- [Tax items](/docs/api/carts/tax-items) may optionally be added with the product. Only administrators with [client_credentials access tokens](/docs/api/authentication/create-an-access-token) are able to do this. If included, they replace any existing taxes on the product.
- The cart currency is set when the first item is added to the cart.
- The product being added to the cart requires a price in the same currency as the other items in the cart. The API returns a 400 error if a price is not defined in the correct currency.
- A cart can contain a maximum of 100 unique items. Items include products, custom items, tax items, and promotions.
- There are a number of actions that happen to your inventory when checking out and paying for an order. For more information, see the [Inventory](/docs/api/pxm/inventory/inventories-introduction) documentation.

:::

### Including Resources

When you make an `Add Product to Cart` request to the catalog-view service, you can obtain details of the component products. If you include the optional parameter `include=component_products` in the request, the response will include details for each component product.

When a bundle with selected component products is added to a cart, the cart displays both the bundle pricing and component product IDs.

The response example is returned with a new field called `component_products` under `bundle_configuration`, which is a list of component products that the user has selected for dynamic bundles.

| Parameter               | Required     | Description        |
|:------------------------|:-------------|:-------------------|
| `component_products`    | Optional     | The component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle. |
| `main_image`            | Optional     | The main images associated with a product. |
| `files`                 | Optional     | Any files associated with a product. |

```json
"bundle_configuration": {
    "selected_options": {
        "mixed-shirts": {
            "16a6cc14-6ebb-4156-9973-e6a0f92f5731": 3,
            "55037cc5-f382-4039-95c6-1e04ac0351d3": 2,
        "standard-shirts"
            "70f1c9d2-c580-4839-bd6c-a0a9b91d5159": 5
        }
    },
    "component_products": [
        {
            "id": "16a6cc14-6ebb-4156-9973-e6a0f92f5731",
            "type": "product",
            "attributes": {
                "name": "Red T-shirt",
                "description": "Standard red t-shirt.",
                "slug": "red-t-shirt-slug",
                "sku": "red-t-shirt-sku",
                "status": "live",
                "commodity_type": "physical"
            },
            "meta": {
                "display_price": {
                    "without_tax": {
                        "amount": 500,
                        "currency": "USD",
                        "formatted": "$5.00"
                    }
                }
            }
        },
        {
            "id": "55037cc5-f382-4039-95c6-1e04ac0351d3",
            "type": "product",
            "attributes": {
                "name": "Blue T-shirt",
                "description": "Standard blue t-shirt.",
                "slug": "blue-t-shirt-slug",
                "sku": "blue-t-shirt-sku",
                "status": "live",
                "commodity_type": "physical"
            },
            "meta": {
                "display_price": {
                    "without_tax": {
                        "amount": 500,
                        "currency": "USD",
                        "formatted": "$5.00"
                    }
                }
            }
        },
        {
            "id": "70f1c9d2-c580-4839-bd6c-a0a9b91d5159",
            "type": "product",
            "attributes": {
                "name": "White T-shirt",
                "description": "Standard white t-shirt.",
                "slug": "white-t-shirt-slug",
                "sku": "white-t-shirt-sku",
                "status": "live",
                "commodity_type": "physical"
            },
            "meta": {
                "display_price": {
                    "without_tax": {
                        "amount": 500,
                        "currency": "USD",
                        "formatted": "$5.00"
                    }
                }
            }
        }
    ]
}
```

See [Including Resources](https://elasticpath.dev/guides/Getting-Started/includes).

### Add Subscription to Cart

To add a subscription to your cart, you need to provide the ID of the subscription offering, and the ID of the pricing option and plan within that offering that you want to subscribe to.

```json
  {
    {
      "data": {
        "id": "5b9be99f-1c94-4ddd-9718-81adab0cc3e0",
        "type": "subscription_item",
        "quantity": 1,
        "subscription_configuration": {
          "plan": "dfa31307-748c-4369-8571-709f924a0807",
          "pricing_option": "40010dde-2f38-489b-8b3f-14a13cbfb431"
        }
    }
  }
```

The price of the subscription item in the cart reflects the cost of the subscription's initial billing period. Once the cart has been checked out and the order paid for, the subscription will be automatically created in the subscriptions service.

### Add Custom Item to Cart

You can add a custom item to the cart when you don't manage things like shipping, taxes and inventory in Commerce.

For [Shipping Groups](/docs/ship-groups/shipping-groups/index), once you have created a [cart shipping group](/docs/ship-groups/shipping-groups/shipping-groups-api/create-cart-shipping-group), you need to link it to the cart items. This is important, because it is necessary to associate items with shipping groups in order to include shipping groups in the corresponding cart, order, and totals.

:::note

- Custom Cart Items are available when using [implicit access tokens](/docs/api/authentication/create-an-access-token). Ensure that you always check each order has the correct details for each item, most importantly, price.

:::

### Add Promotion to Cart

You can use the Promotions API to apply discounts to your cart as a special cart item type. Any requests to add a product to cart will return a collection of cart items.

 There are certain limitations on usage of the `custom_inputs` attribute with some promotion types. See [Limitations on Usage of `custom_inputs` with Specific Promotion Types](/docs/api/carts/manage-carts#limitations-on-usage-of-custom_inputs-with-specific-promotion-types).

To remove promotion from the cart via the promotion code, see [Delete Promotion Code from Cart](/docs/api/carts/delete-a-promotion-via-promotion-code).

### Re-order

From a shopper's order history, they can add the items from a previous order into their carts. Shoppers can add items regardless of past order status, such as incomplete or not paid. For more information, see [Orders](/docs/api/carts/orders).

:::note
  - Any requests to add an item to cart return a collection of [cart items](/docs/api/carts/cart-items).
  - A cart can contain a maximum of 100 unique items. Items include products, custom items, and promotions.
  - When a shopper creates a cart and re-orders items from an order with properties such as custom attributes, custom discounts, and payment intent ID, these properties will remain unchanged in the original cart.
  - Custom items do not exist in catalogs, and therefore cannot be reordered.
:::

### Merging Carts

A shopper can have multiple carts, and the system may automatically merge items from an anonymous cart into the shopper's registered cart when they sign in. For example, if a shopper has an existing cart with items `A`, `B` and `C`, and later adds items `D` and `E` while not signed in, the system can merge these carts when the shopper signs in. After the carts merge, the cart contains items `A`, `B`, `C`, `D` and `E`.

If any items are duplicated from the anonymous cart to the registered cart, their quantities are incremented accordingly. For example, if a shopper's existing cart with items `A`, `B` and `C`, and they later add two more `A` items and one `B` item while not signed in, the system will merge the carts when the shopper signs in. The existing cart will now contain three `A` items, two `B` items, and one `C` item.

:::note

When the system merges items from one cart into another cart, properties such as custom attributes, custom discounts, and payment intent ID will remain unchanged in the original cart.

:::

### Best Practices

We recommend to include a unique `sku` code within the request body while adding custom items to carts. If the same `sku` is used for multiple products, they are merged into a single line item.

For example, if a cart consists of the following items:

- `product-1` with quantity 1 and sku code as `sku-1`
- `product-2` with quantity 1 and sku code as `sku-1`
- `product-3` with quantity 1 and sku code as `sku-2`.

The following response is returned where it combines all products with the same sku codes into a single line item, while products with a unique sku codes are represented as separate items:

```json
{
  "data": [
      {
      "id": "c58760f4-8889-4719-b34d-be1f1d11ae59",
      "type": "custom_item",
      "name": "product-1",
      "description": "My first custom item!",
      "sku": "sku-1",
      "slug": "",
      "image": {
        "mime_type": "",
        "file_name": "",
        "href": ""
      },
      "quantity": 2,
      "manage_stock": false,
      "unit_price": {
        "amount": 20000,
        "currency": "USD",
        "includes_tax": true
      },
      "value": {
        "amount": 40000,
        "currency": "USD",
        "includes_tax": true
        },
      "links": {},
      "meta": {
        "display_price": {
            "with_tax": {
                "unit": {
                  "amount": 20000,
                  "currency": "USD",
                  "formatted": "$200.00"
                },
                "value": {
                  "amount": 40000,
                  "currency": "USD",
                  "formatted": "$400.00"
                    }
                },
            "without_tax": {
                "unit": {
                  "amount": 20000,
                  "currency": "USD",
                  "formatted": "$200.00"
                    },
                "value": {
                  "amount": 40000,
                  "currency": "USD",
                  "formatted": "$400.00"
                    }
                  },
                "tax": {
                  "unit": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                  },
                  "value": {
                      "amount": 0,
                      "currency": "USD",
                      "formatted": "$0.00"
                    }
                  },
                  "discount": {
                      "unit": {
                        "amount": 0,
                        "currency": "USD",
                        "formatted": "$0.00"
                    },
                      "value": {
                        "amount": 0,
                        "currency": "USD",
                        "formatted": "$0.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                           "amount": 20000,
                           "currency": "USD",
                           "formatted": "$200.00"
                          },
                          "value": {
                              "amount": 40000,
                              "currency": "USD",
                              "formatted": "$400.00"
                                }
                              }
                            },
        "timestamps": {
          "created_at": "2023-05-02T16:28:11Z",
          "updated_at": "2023-05-02T16:28:18Z"
        }
    }
  ]
  ```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart that you created.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"oneOf":[{"title":"Cart Item Object Request","type":"object","properties":{"data":{"title":"Cart Item Object Data","allOf":[{"type":"object","required":["type"],"properties":{"type":{"description":"The type of object being returned. Must be `cart_item` for cart items.","type":"string","const":"cart_item"}}},{"title":"Base Item Object Data","type":"object","required":["quantity"],"properties":{"quantity":{"description":"The number of items to add.","type":"number","examples":[2]},"id":{"type":"string","format":"uuid","description":"Specifies the ID of the product you want to add. (use this OR sku)","examples":["78d7b5c2-c852-40ad-87bb-beb161f61f37"]},"sku":{"type":"string","description":"Specifies the item SKU that you want to add. (use this OR id)","examples":["my-item"]},"name":{"type":"string","description":"Optional name for the product item. If not provided, the product name from catalog will be used.","examples":["Custom Product Name"]},"custom_inputs":{"description":"The custom text to be added to a product.","type":"object"},"bundle_configuration":{"description":"Object used to describe the bundle options selected.","type":"object","properties":{"selected_options":{"description":"Specifies selected options.","type":"object"},"component_products":{"description":"Array of component products for the selected options.","type":"array"}}},"shipping_group_id":{"description":"Identifier for a Shipping Group","type":"string"},"location":{"description":"The slug of a stock location.","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}}}}]}}},{"title":"Subscription Item Object","type":"object","properties":{"data":{"allOf":[{"title":"Subscription Item Object Data","type":"object","required":["id","type","quantity","subscription_configuration"],"properties":{"type":{"description":"The type of object being returned.","type":"string","const":"subscription_item"},"quantity":{"description":"The number of items added to the cart.","type":"number","examples":[1]},"id":{"type":"string","format":"uuid","description":"Specifies the ID of the subscription offering you want to add to cart.","examples":["4ca958bc-7d69-4e2d-b5d4-c74bd5a6cde6"]},"subscription_configuration":{"type":"object","description":"Specifies how the subscription offering should be configured.","required":["pricing_option","plan"],"properties":{"pricing_option":{"type":"string","format":"uuid","description":"The ID of the pricing option within the offering to use for the subscription."},"plan":{"type":"string","format":"uuid","description":"The ID of the plan within the offering to use for the subscription.","deprecated":true}}}}},{"title":"Cart Item Response","type":"object","properties":{"id":{"description":"The unique identifier for the cart item.","type":"string","format":"uuid","readOnly":true,"examples":["4649fbb3-b8ee-4883-82c9-49a3d5fbacf1"]},"type":{"description":"The type of cart item.","type":"string","readOnly":true,"enum":["cart_item","custom_item","subscription_item","promotion_item"],"examples":["cart_item"]},"product_id":{"description":"The unique ID of the product (for cart_item type).","type":"string","format":"uuid","readOnly":true,"examples":["55cda543-f9d7-42a4-b40a-665f2e4ff7c5"]},"promotion_id":{"description":"The unique ID of the promotion (for promotion_item type).","type":"string","format":"uuid","readOnly":true,"examples":["9993387e-93ab-468f-bba9-cf13882dc52d"]},"subscription_offering_id":{"description":"The unique ID of the subscription offering for subscription items.","type":"string","format":"uuid","readOnly":true,"examples":["9c13669e-29d7-42ea-bc95-1b32399adb9d"]},"name":{"description":"The name of this item","type":"string","readOnly":true,"examples":["shirt"]},"description":{"description":"A description of the cart item.","type":"string","readOnly":true,"examples":["T-shirt."]},"sku":{"description":"The SKU of the cart item.","type":"string","readOnly":true,"examples":["sample-sku"]},"slug":{"description":"The slug of the cart item.","type":"string","readOnly":true,"examples":["sample-product"]},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if catalog_source=pim is set.","type":"string","readOnly":true,"format":"uuid","examples":["11d3f9d2-c99b-472c-96c3-51842333daea"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","readOnly":true,"examples":["pim"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","readOnly":true,"properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Product ID","type":"string"},"type":{"description":"Product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product meta information as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the cart item for bundle products.","type":"object","readOnly":true,"additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"image":{"type":"object","readOnly":true,"properties":{"mime_type":{"description":"The MIME type for the uploaded file.","type":"string","readOnly":true,"examples":["image/png"]},"file_name":{"description":"The name of the image file that was uploaded.","type":"string","readOnly":true,"examples":["shirt-trans.png"]},"href":{"description":"The link to the image.","type":"string","readOnly":true,"examples":["https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/7cc08cbb-256e-4271-9b01-d03a9fac9f0a.png"]}}},"quantity":{"description":"The quantity of the cart item.","type":"integer","readOnly":true,"examples":[1]},"auto_add_quantity":{"description":"The quantity automatically added (for gift items).","type":"integer","readOnly":true},"manage_stock":{"description":"Whether or not the quantity of the item will be checked against inventory.","type":"boolean","readOnly":true,"examples":[true]},"unit_price":{"description":"The unit price of the item.","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"value":{"description":"The total price of the item (i.e., unit * quantity).","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"discounts":{"description":"Array of discounts applied to the cart item.","type":"array","readOnly":true,"items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"}},"custom_inputs":{"description":"Custom inputs for personalized products.","type":"object","readOnly":true,"additionalProperties":true,"examples":[{"tshirt_front":"John Doe","tshirt_back":"My Custom Text"}]},"subscription_configuration":{"description":"Configuration for subscription items.","type":"object","readOnly":true,"properties":{"plan":{"description":"The subscription plan ID.","type":"string"},"pricing_option":{"description":"The subscription pricing option ID.","type":"string"}}},"links":{"type":"object","readOnly":true,"properties":{"product":{"description":"A URL related to the resource.","type":"string","examples":["https://useast.api.elasticpath.com/products/9eda5ba0-4f4a-4074-8547-ccb05d1b5981"]},"subscription_offering":{"description":"A URL related to the subscription offering resource.","type":"string"}}},"meta":{"type":"object","readOnly":true,"properties":{"display_price":{"type":"object","properties":{"with_tax":{"description":"The amount of this item after discounts and taxes are applied.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_tax":{"description":"The amount of this item after discounts are applied and before taxes.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"tax":{"description":"The amount of taxes applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"discount":{"description":"The amount of the discount applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_discount":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"original_price":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."},"discounts":{"description":"Detailed discount information.","type":"object","additionalProperties":{"type":"object","required":["amount","currency","formatted"],"properties":{"amount":{"description":"The discount amount.","type":"integer","examples":[100]},"currency":{"description":"The currency code.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted discount amount.","type":"string","examples":["$1.00"]},"constituents":{"description":"The discount constituents.","type":"object","additionalProperties":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"description":"Relationships to other resources.","readOnly":true,"type":"object","properties":{"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"custom_discounts":{"description":"Related custom discounts.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"shipping_group_id":{"description":"The shipping group ID for this item.","type":"string","readOnly":true,"examples":["eb063818-939a-458f-97a4-2601c0c2b445"]},"promotion_source":{"description":"The source of the promotion (for promotion items).","type":"string","readOnly":true,"enum":["rule-promotion"],"examples":["rule-promotion"]},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"location":{"description":"The stock location for this item.","type":"string","readOnly":true,"examples":["warehouse-1"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true}}}]}}},{"title":"Cart Merge Object Request","type":"object","properties":{"data":{"allOf":[{"title":"Cart Merge Object","type":"object","required":["type","cart_id"],"properties":{"type":{"description":"The type of object being returned. Must be `cart_items`.","type":"string","const":"cart_items"},"cart_id":{"description":"The original cart to be merged from.","type":"string","format":"uuid","examples":["78d7b5c2-c852-40ad-87bb-beb161f61f37"]}}}],"description":""},"options":{"title":"Add All Or Nothing Options Object","type":"object","properties":{"add_all_or_nothing":{"description":"When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`.","type":"boolean","examples":[false]}}}}},{"title":"Custom Item Object","type":"object","properties":{"data":{"allOf":[{"title":"Custom Item Object Data","type":"object","required":["type","name","quantity","price"],"properties":{"type":{"description":"The type of object being returned. Must be `custom_item`.","type":"string","const":"custom_item"},"quantity":{"description":"The number of custom items to add to cart.","type":"number","examples":[2]},"price":{"type":"object","required":["amount"],"properties":{"amount":{"description":"The unit price of the custom item.","type":"number","examples":[10000]},"includes_tax":{"description":"Set to`true` if relevant taxes have been included in the price, `false` if not. Defaults to `true`.","type":"boolean"}}},"description":{"description":"A description of the custom item.","type":"string","examples":["My first custom item!"]},"sku":{"type":"string","description":"The `SKU` code to use for the custom item. See [best practices](https://elasticpath.dev/docs/commerce-cloud/carts/cart-items/add-custom-item-to-cart#best-practices) to use the `SKU` code.","examples":["my-custom-item"]},"name":{"type":"string","description":"The name of the custom item.","examples":["My Custom Item"]},"custom_inputs":{"description":"The custom text to be added to a product.","type":"object"},"shipping_group_id":{"description":"Identifier for a created Cart Shipping Group","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}}}}],"description":""}}},{"title":"Re-Order Object Request","type":"object","properties":{"data":{"allOf":[{"title":"Re Order Object","type":"object","required":["type","order_id"],"properties":{"type":{"description":"The type of resource being returned. Use `order_items`.","type":"string","const":"order_items"},"order_id":{"description":"The unique identifier of the order.","type":"string","format":"uuid","examples":["78d7b5c2-c852-40ad-87bb-beb161f61f37"]}}}]},"options":{"title":"Add All Or Nothing Options Object","type":"object","properties":{"add_all_or_nothing":{"description":"When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`.","type":"boolean","examples":[false]}}}}},{"title":"Promotion Item Object","type":"object","properties":{"data":{"allOf":[{"title":"Promotion Item Object Data","type":"object","required":["type","code"],"properties":{"type":{"description":"Specifies the type of resource, which is `promotion_item`.","type":"string","const":"promotion_item"},"code":{"description":"Specifies the promotion code. For more information about codes[].user[], see the [Create Promotion codes](/docs/api/promotions/create-promotion-codes) section.","type":"string","examples":["PROMO_CODE"]}}}]}}},{"title":"Bulk Add Items Request","type":"object","properties":{"data":{"type":"array","items":{"anyOf":[{"title":"Cart Item Object Data","allOf":[{"type":"object","required":["type"],"properties":{"type":{"description":"The type of object being returned. Must be `cart_item` for cart items.","type":"string","const":"cart_item"}}},{"title":"Base Item Object Data","type":"object","required":["quantity"],"properties":{"quantity":{"description":"The number of items to add.","type":"number","examples":[2]},"id":{"type":"string","format":"uuid","description":"Specifies the ID of the product you want to add. (use this OR sku)","examples":["78d7b5c2-c852-40ad-87bb-beb161f61f37"]},"sku":{"type":"string","description":"Specifies the item SKU that you want to add. (use this OR id)","examples":["my-item"]},"name":{"type":"string","description":"Optional name for the product item. If not provided, the product name from catalog will be used.","examples":["Custom Product Name"]},"custom_inputs":{"description":"The custom text to be added to a product.","type":"object"},"bundle_configuration":{"description":"Object used to describe the bundle options selected.","type":"object","properties":{"selected_options":{"description":"Specifies selected options.","type":"object"},"component_products":{"description":"Array of component products for the selected options.","type":"array"}}},"shipping_group_id":{"description":"Identifier for a Shipping Group","type":"string"},"location":{"description":"The slug of a stock location.","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}}}}]},{"title":"Cart Merge Object","type":"object","required":["type","cart_id"],"properties":{"type":{"description":"The type of object being returned. Must be `cart_items`.","type":"string","const":"cart_items"},"cart_id":{"description":"The original cart to be merged from.","type":"string","format":"uuid","examples":["78d7b5c2-c852-40ad-87bb-beb161f61f37"]}}},{"title":"Custom Item Object Data","type":"object","required":["type","name","quantity","price"],"properties":{"type":{"description":"The type of object being returned. Must be `custom_item`.","type":"string","const":"custom_item"},"quantity":{"description":"The number of custom items to add to cart.","type":"number","examples":[2]},"price":{"type":"object","required":["amount"],"properties":{"amount":{"description":"The unit price of the custom item.","type":"number","examples":[10000]},"includes_tax":{"description":"Set to`true` if relevant taxes have been included in the price, `false` if not. Defaults to `true`.","type":"boolean"}}},"description":{"description":"A description of the custom item.","type":"string","examples":["My first custom item!"]},"sku":{"type":"string","description":"The `SKU` code to use for the custom item. See [best practices](https://elasticpath.dev/docs/commerce-cloud/carts/cart-items/add-custom-item-to-cart#best-practices) to use the `SKU` code.","examples":["my-custom-item"]},"name":{"type":"string","description":"The name of the custom item.","examples":["My Custom Item"]},"custom_inputs":{"description":"The custom text to be added to a product.","type":"object"},"shipping_group_id":{"description":"Identifier for a created Cart Shipping Group","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}}}},{"title":"Re Order Object","type":"object","required":["type","order_id"],"properties":{"type":{"description":"The type of resource being returned. Use `order_items`.","type":"string","const":"order_items"},"order_id":{"description":"The unique identifier of the order.","type":"string","format":"uuid","examples":["78d7b5c2-c852-40ad-87bb-beb161f61f37"]}}},{"title":"Promotion Item Object Data","type":"object","required":["type","code"],"properties":{"type":{"description":"Specifies the type of resource, which is `promotion_item`.","type":"string","const":"promotion_item"},"code":{"description":"Specifies the promotion code. For more information about codes[].user[], see the [Create Promotion codes](/docs/api/promotions/create-promotion-codes) section.","type":"string","examples":["PROMO_CODE"]}}}]}},"options":{"title":"Add All Or Nothing Options Object","type":"object","properties":{"add_all_or_nothing":{"description":"When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`.","type":"boolean","examples":[false]}}}}}]},"examples":{"Add Cart Item":{"value":{"data":{"type":"cart_item","id":"df32387b-6ce6-4802-9b90-1126a5c5a54f","quantity":1,"custom_inputs":{"name":{"tshirt_front":"Jane","tshirt_back":"Jane Doe's Dance Academy"}}}}},"Add Subscription Item":{"value":{"data":{"type":"subscription_item","id":"1f49c20c-54b9-453b-a57c-ef8303a6415f","quantity":1,"subscription_configuration":{"plan":"dfa31307-748c-4369-8571-709f924a0807","pricing_option":"a2cd9dae-3a28-4185-93b7-1b02a8ce0c2e"}}}},"Add Custom Item":{"value":{"data":{"type":"custom_item","name":"My Custom Item","sku":"my-custom-item","description":"My first custom item!","quantity":1,"price":{"amount":10000}}}},"Add Promotion to Cart":{"value":{"data":{"type":"promotion_item","code":"PROMO_CODE"}}},"Reorder Items":{"value":{"data":{"type":"order_items","order_id":"da0b0a12-8232-4be1-a354-a1a64b11de91"},"options":{"add_all_or_nothing":false}}},"Merge Carts":{"value":{"data":[{"type":"cart_items","cart_id":"da0b0a12-8232-4be1-a354-a1a64b11de91"}],"options":{"add_all_or_nothing":false}}},"Bulk Add Items to Cart":{"value":{"data":[{"type":"cart_item","id":"df32387b-6ce6-4802-9b90-1126a5c5a54f","quantity":1},{"type":"custom_item","name":"My Custom Item","sku":"my-custom-item","description":"My first custom item!","quantity":1,"price":{"amount":10000}},{"type":"promotion_item","code":"PROMO_CODE"}],"options":{"add_all_or_nothing":true}}},"Add Bundle to Cart":{"value":{"data":{"id":"5ab67bb3-b2c3-4348-af33-e370bd39b0c9","type":"cart_item","quantity":1,"bundle_configuration":{"selected_options":{"tshirt":{"23759a57-13c1-4887-9ec2-fb47444751bd":1},"comics":{"c7bcf7fd-1fab-4635-8ae0-7f187a9dbbce":1,"d9768b40-cf28-406e-bafc-a6d130627eca":1}}}}}},"Add Item with Shipping Group ID":{"value":{"data":{"type":"custom_item","name":"My Custom Item","sku":"my-custom-item","description":"My first custom item!","quantity":1,"price":{"amount":10000,"includes_tax":true},"shipping_group_id":"eb063818-939a-458f-97a4-2601c0c2b445"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully added item(s) to cart. When promotions are added, the response includes informational messages in the `meta.messages` field describing the promotion and discount effects.","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Cart Item Response","type":"object","properties":{"id":{"description":"The unique identifier for the cart item.","type":"string","format":"uuid","readOnly":true,"examples":["4649fbb3-b8ee-4883-82c9-49a3d5fbacf1"]},"type":{"description":"The type of cart item.","type":"string","readOnly":true,"enum":["cart_item","custom_item","subscription_item","promotion_item"],"examples":["cart_item"]},"product_id":{"description":"The unique ID of the product (for cart_item type).","type":"string","format":"uuid","readOnly":true,"examples":["55cda543-f9d7-42a4-b40a-665f2e4ff7c5"]},"promotion_id":{"description":"The unique ID of the promotion (for promotion_item type).","type":"string","format":"uuid","readOnly":true,"examples":["9993387e-93ab-468f-bba9-cf13882dc52d"]},"subscription_offering_id":{"description":"The unique ID of the subscription offering for subscription items.","type":"string","format":"uuid","readOnly":true,"examples":["9c13669e-29d7-42ea-bc95-1b32399adb9d"]},"name":{"description":"The name of this item","type":"string","readOnly":true,"examples":["shirt"]},"description":{"description":"A description of the cart item.","type":"string","readOnly":true,"examples":["T-shirt."]},"sku":{"description":"The SKU of the cart item.","type":"string","readOnly":true,"examples":["sample-sku"]},"slug":{"description":"The slug of the cart item.","type":"string","readOnly":true,"examples":["sample-product"]},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if catalog_source=pim is set.","type":"string","readOnly":true,"format":"uuid","examples":["11d3f9d2-c99b-472c-96c3-51842333daea"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","readOnly":true,"examples":["pim"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","readOnly":true,"properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Product ID","type":"string"},"type":{"description":"Product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product meta information as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the cart item for bundle products.","type":"object","readOnly":true,"additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"image":{"type":"object","readOnly":true,"properties":{"mime_type":{"description":"The MIME type for the uploaded file.","type":"string","readOnly":true,"examples":["image/png"]},"file_name":{"description":"The name of the image file that was uploaded.","type":"string","readOnly":true,"examples":["shirt-trans.png"]},"href":{"description":"The link to the image.","type":"string","readOnly":true,"examples":["https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/7cc08cbb-256e-4271-9b01-d03a9fac9f0a.png"]}}},"quantity":{"description":"The quantity of the cart item.","type":"integer","readOnly":true,"examples":[1]},"auto_add_quantity":{"description":"The quantity automatically added (for gift items).","type":"integer","readOnly":true},"manage_stock":{"description":"Whether or not the quantity of the item will be checked against inventory.","type":"boolean","readOnly":true,"examples":[true]},"unit_price":{"description":"The unit price of the item.","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"value":{"description":"The total price of the item (i.e., unit * quantity).","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"discounts":{"description":"Array of discounts applied to the cart item.","type":"array","readOnly":true,"items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"}},"custom_inputs":{"description":"Custom inputs for personalized products.","type":"object","readOnly":true,"additionalProperties":true,"examples":[{"tshirt_front":"John Doe","tshirt_back":"My Custom Text"}]},"subscription_configuration":{"description":"Configuration for subscription items.","type":"object","readOnly":true,"properties":{"plan":{"description":"The subscription plan ID.","type":"string"},"pricing_option":{"description":"The subscription pricing option ID.","type":"string"}}},"links":{"type":"object","readOnly":true,"properties":{"product":{"description":"A URL related to the resource.","type":"string","examples":["https://useast.api.elasticpath.com/products/9eda5ba0-4f4a-4074-8547-ccb05d1b5981"]},"subscription_offering":{"description":"A URL related to the subscription offering resource.","type":"string"}}},"meta":{"type":"object","readOnly":true,"properties":{"display_price":{"type":"object","properties":{"with_tax":{"description":"The amount of this item after discounts and taxes are applied.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_tax":{"description":"The amount of this item after discounts are applied and before taxes.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"tax":{"description":"The amount of taxes applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"discount":{"description":"The amount of the discount applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_discount":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"original_price":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."},"discounts":{"description":"Detailed discount information.","type":"object","additionalProperties":{"type":"object","required":["amount","currency","formatted"],"properties":{"amount":{"description":"The discount amount.","type":"integer","examples":[100]},"currency":{"description":"The currency code.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted discount amount.","type":"string","examples":["$1.00"]},"constituents":{"description":"The discount constituents.","type":"object","additionalProperties":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"description":"Relationships to other resources.","readOnly":true,"type":"object","properties":{"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"custom_discounts":{"description":"Related custom discounts.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"shipping_group_id":{"description":"The shipping group ID for this item.","type":"string","readOnly":true,"examples":["eb063818-939a-458f-97a4-2601c0c2b445"]},"promotion_source":{"description":"The source of the promotion (for promotion items).","type":"string","readOnly":true,"enum":["rule-promotion"],"examples":["rule-promotion"]},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"location":{"description":"The stock location for this item.","type":"string","readOnly":true,"examples":["warehouse-1"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true}}}},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"type":"object","properties":{"automatic":{"type":"boolean"},"description":{"type":"string"},"end":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"promotion_type":{"type":"string"},"promotion_source":{"type":"string","description":"The source of the promotion"},"start":{"type":"string","format":"date-time"},"type":{"type":"string","const":"promotion"}}}},"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}}}},"meta":{"type":"object","description":"Additional meta information about the cart items collection.","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"balance_owing":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"messages":{"type":"array","description":"Optional array of informational messages that provide feedback about operations performed on the cart items, such as promotions added or discounts applied. This field is only present when there are relevant messages to display.\n","items":{"type":"object","properties":{"source":{"type":"object","description":"Identifies the cart item that triggered this message","properties":{"type":{"type":"string","description":"The type of the source item"},"id":{"type":"string","description":"The unique identifier of the source item"},"code":{"type":"string","description":"The promotion code (present when source type is promotion)"}},"required":["type","id"]},"title":{"type":"string","description":"A short descriptive title for the message"},"description":{"type":"string","description":"A detailed description of the message"}},"required":["title","description"]}},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"},"auto_add":{"type":"boolean","description":"Whether this promotion should be automatically added"},"targets":{"description":"Array of promotion targets (alternative structure)","type":"array","items":{"type":"object","properties":{"cart_item_id":{"type":"string","description":"The cart item ID for this target"},"quantity":{"type":"integer","description":"The quantity for this target"},"skus":{"type":"array","description":"Array of SKU codes for this target","items":{"type":"string"}}}}}}}}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"required":["data"],"title":"CartItemCollectionResponse"},"examples":{"promotion-added-with-messages":{"summary":"Successful promotion addition with messages (cart discount with promotion_item)","value":{"data":[{"id":"1359223e-5de0-4d42-a2ec-14350a84c173","type":"custom_item","name":"My Custom Item","description":"My first custom item!","sku":"Sample-sku","slug":"","image":{"mime_type":"","file_name":"","href":""},"quantity":1,"manage_stock":false,"unit_price":{"amount":10000,"currency":"USD","includes_tax":true},"value":{"amount":10000,"currency":"USD","includes_tax":true},"discounts":[{"amount":{"amount":-1000,"currency":"USD","includes_tax":false},"code":"auto_4c8cc302-b1e8-4d1e-a1d5-fb74fda83705","id":"4c8cc302-b1e8-4d1e-a1d5-fb74fda83705","promotion_source":"rule-promotion","is_cart_discount":true,"ordinal":1}],"links":{},"meta":{"display_price":{"with_tax":{"unit":{"amount":9000,"currency":"USD","formatted":"$90.00"},"value":{"amount":9000,"currency":"USD","formatted":"$90.00"}},"without_tax":{"unit":{"amount":9000,"currency":"USD","formatted":"$90.00"},"value":{"amount":9000,"currency":"USD","formatted":"$90.00"}},"tax":{"unit":{"amount":0,"currency":"USD","formatted":"$0.00"},"value":{"amount":0,"currency":"USD","formatted":"$0.00"}},"discount":{"unit":{"amount":-1000,"currency":"USD","formatted":"-$10.00"},"value":{"amount":-1000,"currency":"USD","formatted":"-$10.00"}},"without_discount":{"unit":{"amount":10000,"currency":"USD","formatted":"$100.00"},"value":{"amount":10000,"currency":"USD","formatted":"$100.00"}},"discounts":{"auto_4c8cc302-b1e8-4d1e-a1d5-fb74fda83705":{"amount":-1000,"currency":"USD","formatted":"-$10.00","constituents":{"4c8cc302-b1e8-4d1e-a1d5-fb74fda83705":{"amount":-1000,"currency":"USD","formatted":"-$10.00"}}}}},"timestamps":{"created_at":"2025-09-10T22:28:29Z","updated_at":"2025-09-10T22:28:29Z"}}},{"id":"7a7fb70a-561a-4caf-a112-c3e5a74145f4","type":"promotion_item","promotion_id":"4c8cc302-b1e8-4d1e-a1d5-fb74fda83705","name":"cart auto","description":"Promotion","sku":"auto_4c8cc302-b1e8-4d1e-a1d5-fb74fda83705","slug":"","image":{"mime_type":"","file_name":"","href":""},"quantity":1,"manage_stock":false,"unit_price":{"amount":-1000,"currency":"USD","includes_tax":false},"value":{"amount":-1000,"currency":"USD","includes_tax":false},"links":{},"meta":{"display_price":{"with_tax":{"unit":{"amount":-1000,"currency":"USD","formatted":"-$10.00"},"value":{"amount":-1000,"currency":"USD","formatted":"-$10.00"}},"without_tax":{"unit":{"amount":-1000,"currency":"USD","formatted":"-$10.00"},"value":{"amount":-1000,"currency":"USD","formatted":"-$10.00"}},"tax":{"unit":{"amount":0,"currency":"USD","formatted":"$0.00"},"value":{"amount":0,"currency":"USD","formatted":"$0.00"}},"discount":{"unit":{"amount":0,"currency":"USD","formatted":"$0.00"},"value":{"amount":0,"currency":"USD","formatted":"$0.00"}},"without_discount":{"unit":{"amount":0,"currency":"","formatted":"0"},"value":{"amount":0,"currency":"","formatted":"0"}}},"timestamps":{"created_at":"2025-09-10T22:28:29Z","updated_at":"2025-09-10T22:28:29Z"}},"promotion_source":"rule-promotion"}],"meta":{"display_price":{"with_tax":{"amount":9000,"currency":"USD","formatted":"$90.00"},"without_tax":{"amount":9000,"currency":"USD","formatted":"$90.00"},"tax":{"amount":0,"currency":"USD","formatted":"$0.00"},"discount":{"amount":-1000,"currency":"USD","formatted":"-$10.00"},"without_discount":{"amount":10000,"currency":"USD","formatted":"$100.00"},"shipping":{"amount":0,"currency":"USD","formatted":"$0.00"},"shipping_discount":{"amount":0,"currency":"USD","formatted":"$0.00"}},"timestamps":{"created_at":"2025-09-08T13:17:42Z","updated_at":"2025-09-10T22:28:29Z","expires_at":"2025-09-17T22:28:29Z"},"messages":[{"source":{"type":"promotion_item","id":"7a7fb70a-561a-4caf-a112-c3e5a74145f4"},"title":"Promotion Added","description":"Promotion has been added to cart."},{"source":{"type":"custom_item","id":"1359223e-5de0-4d42-a2ec-14350a84c173"},"title":"Discount Added","description":"Item discount has been added."}]}}},"item-discount-only":{"summary":"Successful promotion with item discount only","value":{"data":[{"id":"5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34","type":"custom_item","name":"Sample Product","sku":"sample-sku","quantity":1,"unit_price":{"amount":10000,"currency":"USD","includes_tax":false},"value":{"amount":9000,"currency":"USD","includes_tax":false},"discounts":[{"amount":{"amount":-1000,"currency":"USD","includes_tax":false},"code":"DISCOUNT10","id":"9993387e-93ab-468f-bba9-cf13882dc52d","promotion_source":"rule-promotion"}]}],"meta":{"display_price":{"with_tax":{"amount":9000,"currency":"USD","formatted":"$90.00"},"without_tax":{"amount":9000,"currency":"USD","formatted":"$90.00"},"tax":{"amount":0,"currency":"USD","formatted":"$0.00"},"discount":{"amount":-1000,"currency":"USD","formatted":"-$10.00"},"without_discount":{"amount":10000,"currency":"USD","formatted":"$100.00"},"shipping":{"amount":0,"currency":"USD","formatted":"$0.00"},"shipping_discount":{"amount":0,"currency":"USD","formatted":"$0.00"}},"timestamps":{"created_at":"2025-09-08T13:17:42Z","updated_at":"2025-09-10T13:45:54Z","expires_at":"2025-09-17T13:45:54Z"},"messages":[{"source":{"type":"custom_item","id":"5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34"},"title":"Discount Added","description":"Item discount has been added."}]}}},"non-stackable-promotion-replacement":{"summary":"Higher priority promotion replaces lower priority non-stackable promotion","value":{"data":[{"id":"5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34","type":"custom_item","name":"Sample Product","sku":"sample-sku","quantity":1,"unit_price":{"amount":10000,"currency":"USD","includes_tax":false},"value":{"amount":8000,"currency":"USD","includes_tax":false},"discounts":[{"amount":{"amount":-2000,"currency":"USD","includes_tax":false},"code":"HIGHER-PRIORITY-CODE","id":"a8f4b123-5678-4abc-9def-123456789abc","promotion_source":"rule-promotion"}]}],"meta":{"display_price":{"with_tax":{"amount":8000,"currency":"USD","formatted":"$80.00"},"without_tax":{"amount":8000,"currency":"USD","formatted":"$80.00"},"tax":{"amount":0,"currency":"USD","formatted":"$0.00"},"discount":{"amount":-2000,"currency":"USD","formatted":"-$20.00"},"without_discount":{"amount":10000,"currency":"USD","formatted":"$100.00"},"shipping":{"amount":0,"currency":"USD","formatted":"$0.00"},"shipping_discount":{"amount":0,"currency":"USD","formatted":"$0.00"}},"timestamps":{"created_at":"2025-09-08T13:17:42Z","updated_at":"2025-09-10T13:45:54Z","expires_at":"2025-09-17T13:45:54Z"},"messages":[{"source":{"type":"promotion","id":"5fe6a1f5-d0ec-4fdc-a115-49f271a6694d","code":"lower-priority-code"},"title":"Couldn't Stack Promotion","description":"Cannot apply promotion because non-stackable promotion applied first."},{"source":{"type":"custom_item","id":"5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34"},"title":"Discount Added","description":"Item discount has been added."},{"source":{"type":"custom_item","id":"5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34"},"title":"Discount Deleted","description":"Item discount has been removed."}]}}},"lower-priority-promotion-rejected":{"summary":"Lower priority promotion rejected when higher priority promotion already applied","value":{"data":[{"id":"5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34","type":"custom_item","name":"Sample Product","sku":"sample-sku","quantity":1,"unit_price":{"amount":10000,"currency":"USD","includes_tax":false},"value":{"amount":7500,"currency":"USD","includes_tax":false},"discounts":[{"amount":{"amount":-2500,"currency":"USD","includes_tax":false},"code":"HIGHER-PRIORITY-CODE","id":"a8f4b123-5678-4abc-9def-123456789abc","promotion_source":"rule-promotion"}]}],"meta":{"display_price":{"with_tax":{"amount":7500,"currency":"USD","formatted":"$75.00"},"without_tax":{"amount":7500,"currency":"USD","formatted":"$75.00"},"tax":{"amount":0,"currency":"USD","formatted":"$0.00"},"discount":{"amount":-2500,"currency":"USD","formatted":"-$25.00"},"without_discount":{"amount":10000,"currency":"USD","formatted":"$100.00"},"shipping":{"amount":0,"currency":"USD","formatted":"$0.00"},"shipping_discount":{"amount":0,"currency":"USD","formatted":"$0.00"}},"timestamps":{"created_at":"2025-09-08T13:17:42Z","updated_at":"2025-09-10T13:45:54Z","expires_at":"2025-09-17T13:45:54Z"},"messages":[{"source":{"type":"promotion","id":"5fe6a1f5-d0ec-4fdc-a115-49f271a6694d","code":"lower-priority-code"},"title":"Couldn't Stack Promotion","description":"Cannot apply promotion because non-stackable promotion applied first."}]}}},"bulk-non-stackable-promotions":{"summary":"Bulk request with two non-stackable promotions - higher priority wins","value":{"data":[{"id":"1e64d793-0ee4-4c06-9875-a3c4ea3320b2","type":"custom_item","name":"Sample Product","sku":"sample-sku","quantity":1,"unit_price":{"amount":10000,"currency":"USD","includes_tax":false},"value":{"amount":7000,"currency":"USD","includes_tax":false},"discounts":[{"amount":{"amount":-3000,"currency":"USD","includes_tax":false},"code":"HIGHER-PRIORITY-CODE","id":"a8f4b123-5678-4abc-9def-123456789abc","promotion_source":"rule-promotion"}]}],"meta":{"display_price":{"with_tax":{"amount":7000,"currency":"USD","formatted":"$70.00"},"without_tax":{"amount":7000,"currency":"USD","formatted":"$70.00"},"tax":{"amount":0,"currency":"USD","formatted":"$0.00"},"discount":{"amount":-3000,"currency":"USD","formatted":"-$30.00"},"without_discount":{"amount":10000,"currency":"USD","formatted":"$100.00"},"shipping":{"amount":0,"currency":"USD","formatted":"$0.00"},"shipping_discount":{"amount":0,"currency":"USD","formatted":"$0.00"}},"timestamps":{"created_at":"2025-09-08T13:17:42Z","updated_at":"2025-09-10T13:45:54Z","expires_at":"2025-09-17T13:45:54Z"},"messages":[{"source":{"type":"promotion","id":"5fe6a1f5-d0ec-4fdc-a115-49f271a6694d","code":"lower-priority-code"},"title":"Couldn't Stack Promotion","description":"Cannot apply promotion because non-stackable promotion applied first."},{"source":{"type":"custom_item","id":"f958fe86-7f85-4212-8782-ecda6a52987a"},"title":"Discount Added","description":"Item discount has been added."}]}}},"bulk-partial-success":{"summary":"Bulk operation partial success - valid promotion applied, invalid promotion in errors","value":{"data":[{"id":"74ab3008-a663-49a1-832b-6d3925b8a94d","type":"custom_item","name":"My Custom Item","description":"My first custom item!","sku":"dog-bed","quantity":1,"unit_price":{"amount":10000,"currency":"USD","includes_tax":true},"value":{"amount":10000,"currency":"USD","includes_tax":true},"discounts":[{"amount":{"amount":-500,"currency":"USD","includes_tax":false},"code":"valid-code","id":"5fe6a1f5-d0ec-4fdc-a115-49f271a6694d","promotion_source":"rule-promotion","ordinal":1}],"meta":{"display_price":{"with_tax":{"unit":{"amount":9500,"currency":"USD","formatted":"$95.00"},"value":{"amount":9500,"currency":"USD","formatted":"$95.00"}},"without_tax":{"unit":{"amount":9500,"currency":"USD","formatted":"$95.00"},"value":{"amount":9500,"currency":"USD","formatted":"$95.00"}},"discount":{"unit":{"amount":-500,"currency":"USD","formatted":"-$5.00"},"value":{"amount":-500,"currency":"USD","formatted":"-$5.00"}},"without_discount":{"unit":{"amount":10000,"currency":"USD","formatted":"$100.00"},"value":{"amount":10000,"currency":"USD","formatted":"$100.00"}},"discounts":{"valid-code":{"amount":-500,"currency":"USD","formatted":"-$5.00","constituents":{"5fe6a1f5-d0ec-4fdc-a115-49f271a6694d":{"amount":-500,"currency":"USD","formatted":"-$5.00"}}}}},"timestamps":{"created_at":"2025-09-10T14:18:34Z","updated_at":"2025-09-10T14:18:34Z"}}}],"errors":[{"status":404,"title":"Not Found","detail":"No promotion could be found with the given code.","meta":{"code":"invalid-code"}}],"meta":{"display_price":{"with_tax":{"amount":9500,"currency":"USD","formatted":"$95.00"},"without_tax":{"amount":9500,"currency":"USD","formatted":"$95.00"},"tax":{"amount":0,"currency":"USD","formatted":"$0.00"},"discount":{"amount":-500,"currency":"USD","formatted":"-$5.00"},"without_discount":{"amount":10000,"currency":"USD","formatted":"$100.00"},"shipping":{"amount":0,"currency":"USD","formatted":"$0.00"},"shipping_discount":{"amount":0,"currency":"USD","formatted":"$0.00"}},"timestamps":{"created_at":"2025-09-08T13:17:42Z","updated_at":"2025-09-10T14:18:57Z","expires_at":"2025-09-17T14:18:57Z"},"messages":[{"source":{"type":"custom_item","id":"74ab3008-a663-49a1-832b-6d3925b8a94d"},"title":"Discount Added","description":"Item discount has been added."}]}}},"bulk-product-partial-success":{"summary":"Bulk product addition - one product added successfully, one product not found","value":{"data":[{"id":"6585a5bb-fce7-4fb3-8693-2c930d53746c","type":"cart_item","product_id":"25c98289-6303-4d09-a2a2-b27cc90fc3f8","name":"Dairy Milk","description":"","sku":"dairy-milk","slug":"dairy-milk","quantity":1,"unit_price":{"amount":400,"currency":"USD","includes_tax":false},"value":{"amount":400,"currency":"USD","includes_tax":false},"links":{"product":"https://epcc-integration.global.ssl.fastly.net/v2/products/25c98289-6303-4d09-a2a2-b27cc90fc3f8"},"meta":{"display_price":{"with_tax":{"unit":{"amount":400,"currency":"USD","formatted":"$4.00"},"value":{"amount":400,"currency":"USD","formatted":"$4.00"}},"without_tax":{"unit":{"amount":400,"currency":"USD","formatted":"$4.00"},"value":{"amount":400,"currency":"USD","formatted":"$4.00"}},"tax":{"unit":{"amount":0,"currency":"USD","formatted":"$0.00"},"value":{"amount":0,"currency":"USD","formatted":"$0.00"}},"discount":{"unit":{"amount":0,"currency":"USD","formatted":"$0.00"},"value":{"amount":0,"currency":"USD","formatted":"$0.00"}},"without_discount":{"unit":{"amount":400,"currency":"USD","formatted":"$4.00"},"value":{"amount":400,"currency":"USD","formatted":"$4.00"}}},"timestamps":{"created_at":"2025-09-10T14:22:54Z","updated_at":"2025-09-10T14:22:54Z"}},"catalog_id":"f8606b9b-2a6f-4037-b47f-3254246d9ad2","catalog_source":"pim"}],"errors":[{"status":404,"title":"Product not found","detail":"product SKU 'invalid-sku' not found in catalog release 'latestPublished' in store ID '42527cca-7c30-4658-827f-734c36d4aca1': not found","meta":{"sku":"invalid-sku"}}],"meta":{"display_price":{"with_tax":{"amount":400,"currency":"USD","formatted":"$4.00"},"without_tax":{"amount":400,"currency":"USD","formatted":"$4.00"},"tax":{"amount":0,"currency":"USD","formatted":"$0.00"},"discount":{"amount":0,"currency":"USD","formatted":"$0.00"},"without_discount":{"amount":400,"currency":"USD","formatted":"$4.00"},"shipping":{"amount":0,"currency":"USD","formatted":"$0.00"},"shipping_discount":{"amount":0,"currency":"USD","formatted":"$0.00"}},"timestamps":{"created_at":"2025-09-08T13:17:42Z","updated_at":"2025-09-10T14:22:54Z","expires_at":"2025-09-17T14:22:54Z"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Invalid Price","value":{"errors":[{"detail":"Must be greater than or equal to 0","meta":{"value":-100000},"status":400,"title":"number_gte"}]}}}}}},"403":{"description":"Unauthorized call","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"No permissions to use custom attributes","value":{"errors":[{"detail":"No permissions to fulfill this request with cart item custom_attributes","status":403,"title":"Unauthorised call"}]}}}}}},"404":{"description":"Not Found - occurs when a referenced product or promotion cannot be found. For bulk operations with add_all_or_nothing=true, the entire operation fails if any item is invalid.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"A referenced product could not be found","value":{"errors":[{"detail":"The requested product could not be found","meta":{"id":"1c73326e-07e0-4043-81fc-54b8f13daeb4"},"status":404,"title":"Product not found"}]}},"invalid-promotion-code":{"summary":"Invalid or ineligible promotion code","value":{"errors":[{"detail":"No promotion could be found with the given code.","meta":{"code":"invalid-code"},"status":404,"title":"Not Found"}]}},"bulk-add-all-or-nothing-failure":{"summary":"Bulk add items fails when add_all_or_nothing is true and one item is invalid","value":{"errors":[{"detail":"No promotion could be found with the given code.","meta":{"code":"invalid-code"},"status":404,"title":"Not Found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Could not apply EP promotion with the given code","value":{"errors":[{"detail":"The cart is configured to use custom discounts","meta":{"code":"10_OFF","ids":["0e5bae32-cc71-4ede-8d7d-cb662e90c542"]},"status":422,"title":"Could not apply EP promotion with the given code"}]}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Orders

An Order is created through the [checkout](/docs/api/carts/checkout) endpoint within the Carts API.

An order is created after a customer checks out their cart. On creation, the order is marked unpaid. The customer is prompted for a shipping address, a billing address, and a payment method. After the order is successfully paid, you can trigger an inventory process and a shipping process.

You can keep a history of orders associated with the customer account.

### Reorder

A re-order is when a shopper copies items from a previous order from their order history into a cart of their choice. If a shopper re-orders to an empty cart, the same quantities as the past order are applied. If the shopper re-orders to an existing cart, and orders the same item, the quantity increases. If an item is out of stock, the item is not added to the cart, and the shopper sees an insufficient stock error. The tax for the items in a re-order is not applied. For more information, see [Tax Items](/docs/api/carts/tax-items).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Payments

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Payments"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/orders/{orderID}/payments"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Depending on the payment gateway, you may have access to different transaction types such as capturing funds immediately or authorizing them for later. For more information, see [Payments](/docs/api/carts/payments).

The following types of payment methods are available depending on the payment gateway:

- `purchase`: This is the simplest method. The gateway attempts to charge the customer immediately.
- `authorize`: This method authorizes a payment so that funds can be captured later, for example, when an item is dispatched or restocked.
- `purchase_setup`: This method prepares the system for a purchase by verifying payment details without actually charging the customer. For example, a customer adds items to their cart and proceeds to checkout. Before finalizing the purchase, the system runs `purchase_setup` to confirm all payment details, but no funds are transferred until the customer confirms the order.
- `authorize_setup`: This method prepares the system for an authorization-only transaction. This process holds the necessary funds but does not transfer them, ensuring that the customer has sufficient balance for the transaction. It sets up the conditions for a future capture of the authorized funds. For example, a customer places a pre-order for a product that will ship in two weeks. The merchant uses `authorize_setup` to prepare for the payment authorization. This holds the customer's funds to ensure they can cover the purchase but waits to capture the payment until the product ships. This ensures that payment is secured but not collected prematurely.

:::note

Split payments can be performed using any methods for any gateway.

- You can partially pay funds using `purchase` method. The gateway attempts to charge the customer immediately, and the payment status for an order will show `partially_paid`
- You can partially pay for an order using `authorize` method where the order will be marked as `partially_authorized`. The transaction must be completed for the order status to be `partially_authorized`.
- A `purchase_setup` method allows verification of payment details for partial payments without transferring funds until the customer confirms the full order.
- An `authorize_setup` method can be used to hold a partial amount of the total funds, ensuring the customer has enough balance for a future capture.
Until a payment is made neither `purchase_setup` nor `authorize_setup` affects the payment statuses, and the order remains unpaid. For more information about order and payment statuses for split payments, see [Split payments](/docs/api/payments/payment-gateways-introduction#split-payments).

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The Universally Unique Identifier (UUID) of the order you want to pay for.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"PaymentsRequest","type":"object","properties":{"data":{"oneOf":[{"title":"Data.AdyenPayment","required":["payment","gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the gateway. You must use `adyen`.","type":"string","const":"adyen"},"options":{"type":"object","properties":{"shopper_reference":{"description":"The shopper reference token associated with the saved payment method.","type":"string"},"recurring_processing_model":{"description":"Enter CardOnFile for a one-time purchase.","type":"string"}}},"payment":{"description":"The Adyen recurringDetailReference payment method identifier.","type":"string"}}}]},{"title":"Data.AuthorizeNetPayment","required":["payment","gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the gateway. You must use `authorize_net`.","type":"string","const":"authorize_net"},"options":{"type":"object","properties":{"customer_payment_profile_id":{"description":"The Authorize.net customer payment profile ID.","type":"string"}}},"payment":{"description":"The Authorize.net customer profile ID.","type":"string"}}}]},{"title":"Data.BraintreePayment","required":["payment","gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the gateway. You must use `braintree`.","type":"string","const":"braintree"},"payment":{"description":"The Braintree Customer ID that you want to bill.","type":"string"}}}]},{"title":"Data.CardConnectPayment","required":["payment","gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the gateway. You must use `card_connect`.","type":"string","const":"card_connect"},"payment":{"description":"Enter account_id, profile_id from CardPointe API. For example, 1|16178397535388255208.","type":"string"}}}]},{"title":"Data.CyberSourcePayment","required":["payment","gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the gateway. You must use `cyber_source`.","type":"string","const":"cyber_source"},"payment":{"description":"The CyberSource token.","type":"string"}}}]},{"title":"Elastic Path Payments Powered By Stripe","type":"object","properties":{"data":{"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the gateway. You must use `elastic_path_payments_stripe`.","type":"string","const":"elastic_path_payments_stripe"},"options":{"type":"object","properties":{"receipt_email":{"description":"Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode.","type":"string"},"automatic_payment_methods":{"type":"object","description":"Parent object determining whether to use Stripe's `automatic_payment_methods` setting.","properties":{"enabled":{"type":"boolean","description":"When set to true, it displays all enabled payment methods from the Stripe dashboard. When set to false, the Stripe default, which is card, is used."}}}}},"payment_method_types":{"type":"array","items":{"type":"string"},"description":"Specifies the Stripe payment method types configured for the store. See [Stripe Documentation](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types).","examples":[["card"]]},"payment":{"description":"Specifies the Stripe token or source.","type":"string"}}}]}}},{"title":"Data.ManualPayment","required":["gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the type of payment gateway. You must use `manual`.","type":"string","const":"manual"},"paymentmethod_meta":{"type":"object","properties":{"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend not to include personal information in this field.","type":"string"},"name":{"description":"A custom name associated with the payment method.","type":"string"}}}}}]},{"title":"Data.PayPalExpressCheckoutPayment","required":["gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the type of payment gateway. You must use `paypal_express_checkout`.","type":"string","const":"paypal_express_checkout"},"options":{"type":"object","properties":{"description":{"description":"The description for the payment.","type":"string"},"soft_descriptor":{"description":"The descriptor appended to PayPal generated descriptor that is visible on the card statement of the payer.","type":"string"},"application_context":{"type":"object","properties":{"brand_name":{"description":"The label that overrides the business name in the PayPal account on the PayPal site.","type":"string"},"locale":{"description":"The locale pages that appear based on language and country code. PayPal supports a five-character code. For example, ja-JP.","type":"string"},"landing_page":{"description":"The type of landing page to show on the PayPal site for customer checkout. Use values LOGIN, BILLING, or NO_PREFERENCE.","type":"string"},"shipping_preference":{"description":"The shipping preference. Use SET_PROVIDED_ADDRESS value. This parameter does allow the user to change their address on PayPal site.","type":"string"},"user_action":{"description":"If you set `useraction=commit` in the query string, the flow redirects the buyer to the PayPal payment page and displays a Pay Now button. When the shopper clicks **Pay Now**, call `DoExpressCheckoutPayment` to complete the payment without additional interaction from the shopper. Choose this flow when you know the final payment amount when you initiate the checkout flow.","type":"string"},"return_url":{"description":"The callback URL for PayPal to redirect the user in the case of approved payment.","type":"string"},"cancel_url":{"description":"The callback URL for PayPal to redirect user in the case a cancelled payment.","type":"string"}}}}}}}]},{"title":"Data.StripePayment","required":["gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the type of payment gateway. You must use `stripe`.","type":"string","const":"stripe"},"options":{"type":"object","properties":{"receipt_email":{"description":"The option to provide an email for Stripe receipts. Specify live mode to access this feature.","type":"string"}}},"payment":{"description":"The Stripe token or source.","type":"string"}}}]},{"title":"Data.StripePaymentIntentsPayment","required":["gateway"],"allOf":[{"title":"Data.BasePayments","type":"object","required":["gateway","method"],"properties":{"gateway":{"type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents"]},"method":{"description":"Specifies the transaction method, such as `purchase` or `authorize`.","type":"string","enum":["authorize","purchase","purchase_setup","authorize_setup"]},"amount":{"description":"The amount to be paid for the transaction.","type":"number","examples":[10000]}}},{"type":"object","properties":{"gateway":{"description":"Specifies the type of payment gateway. You must use `stripe_payment_intents`.","type":"string","const":"stripe_payment_intents"},"options":{"type":"object","properties":{"receipt_email":{"description":"Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode.","type":"string"}}},"payment":{"description":"Specifies the Stripe token or source.","type":"string"}}}]}],"title":"Data.PaymentObject"}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"TransactionResponse","properties":{"id":{"description":"The ID of the transaction.","type":"string","format":"uuid","readOnly":true},"reference":{"description":"The payment gateway reference.","type":"string","examples":["manual"]},"name":{"description":"A custom name associated with the payment method.","type":"string","examples":["payment method name"]},"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.","type":"string","examples":["custom reference"]},"gateway":{"description":"The name of the payment gateway used.","type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents","stripe_platform_account"]},"amount":{"description":"The amount for this transaction.","type":"number","examples":[10000]},"refunded_amount":{"description":"The refunded amount.","type":"number","examples":[0]},"currency":{"description":"The transaction currency.","type":"string","examples":["USD"]},"transaction_type":{"description":"The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`.","type":"string","enum":["purchase","authorize","capture","refund"]},"type":{"description":"The type of object being returned.","type":"string"},"status":{"description":"The status provided by the gateway for this transaction, such as `complete` or `failed`.","type":"string","examples":["complete"]},"payment_details":{"description":"Payment gateway specific details.","type":"object","properties":{"detailed_status":{"description":"Detailed status from the payment gateway.","type":"string"}}},"failure_details":{"description":"Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information.","title":"FailureDetails","type":"object","properties":{"code":{"description":"Machine-readable failure or error code from the payment gateway.","type":"string","examples":["2"]},"reason":{"description":"Human-readable failure reason or error message from the payment gateway.","type":"string","examples":["This transaction has been declined."]}}},"payment_intent":{"description":"Payment intent details.","type":"object","additionalProperties":true},"capture_mechanism":{"description":"The mechanism used for capturing the transaction.","type":"string","enum":["automatic","manual"]},"refund_mechanism":{"description":"The mechanism used for refunding the transaction.","type":"string","enum":["automatic","manual"]},"client_parameters":{"description":"Client-specific parameters for payment processing.","type":"object","properties":{"redirect_url":{"description":"URL to redirect the client after payment.","type":"string"},"secret":{"description":"Client secret for payment processing.","type":"string"},"token":{"description":"Client token for payment processing.","type":"string"}}},"next_actions":{"description":"Array of next actions for the transaction.","type":"array","items":{"type":"string"}},"relationships":{"type":"object","properties":{"order":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Represents the type of the object being returned. It is always `order`.","type":"string","examples":["order"]},"id":{"description":"The ID of the order.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}},"meta":{"type":"object","properties":{"display_price":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"display_refunded_amount":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}}}}},"required":["data"],"title":"TransactionEntityResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Required field missing","value":{"errors":[{"detail":"Request could not be processed","status":"400","title":"Bad Request"}]}}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Payments(Carts)

When you [checkout](/docs/api/carts/checkout) a [cart](/docs/api/carts/cart-management), an unpaid [order](/docs/api/carts/orders) is returned. You can process the payment for the order though a payment gateway.

:::note

- You need to configure and enable a payment gateway before you can accept payments for orders.
- Configure your store to use [Manual Gateway](/docs/api/payments/update-manual-gateway) to process payments if the order total is zero or the payment is through non-supported payment providers.
- There are a number of actions that happen to your inventory when checking out and paying for an order. For more information, see [Inventory](/docs/api/pxm/inventory/inventories-introduction).
- We recommend to wait until the payment confirmation process is fully completed before proceeding with any additional updates to the order. Making simultaneous updates to the same entity immediately after payment confirmation can lead to a race condition. To learn more information on handling parallel calls to API objects, see [Parallel Calls to API Objects](/guides/Getting-Started/api-contract#parallel-calls-to-api-objects).

:::

### Payment Methods

Depending on the chosen gateway, you may or may not have access to capture funds immediately or authorize for later payment.

To make a partial payment in Postman through any payment gateway, specify the desired payment amount in the amount field within the request body. To learn about Split Payments, see the [Split Payments](/docs/api/payments/payment-gateways-introduction#split-payments) section.

#### Purchase

The simplest method is purchase. The gateway attempts to charge the customer immediately, and the result of the attempt is returned.

You can partially pay funds using purchase method. The gateway attempts to charge the customer immediately, and the payment status for an order shows `partially_paid`.

When you Get an order, you can see the following fields in the `meta` object:

- `balance_owing`: Specifies the outstanding funds required to complete an order. It considers all complete or pending transactions, including authorized, paid, and captured transactions. (`balance_owing` = order total - `authorized` amount - `paid` amount).
- `paid`: Specifies the total amount of purchased or captured transactions.
- `authorized`: Specifies the total amount of completed or pending authorized transactions for an order.

#### Authorize

You can `authorize` a payment so funds can later be captured when an item is dispatched or restocked.

You can partially pay for an order using `authorize` payment method so that the order is `partially_authorized`. The transaction must be complete for the order status to be `partially_authorized`.

For more information about order and payment statuses for split payments, see [Split Payments](/docs/api/payments/payment-gateways-introduction#split-payments).

#### Capture

After authorizing a transaction, you have to capture the authorized funds.

:::note

We recommend capturing payments several hours to days after the authorization to mitigate risks of fraud and chargebacks. When you sell digital goods that are delivered immediately, we recommend using a single purchase call instead of separate authorize and capture calls.

:::

After the payment is `partially_authorized`, you must `capture` the authorized transaction later. Once you capture the authorized transactions, the order payment status will change to `partially_paid`.

#### Refunds

You can use either the Refund through Composable Commerce or use the Mark as Refunded capability, or a combination of both capabilities.

For more information about refund for split payments, see [Refund a Payment](/docs/api/carts/refund-a-transaction).

#### Refund through Composable Commerce

You can start a full or partial refund to a supported payment provider directly from Commerce Manager or the API. When you start the refund process, the refund request is sent to the payment gateway. You no longer have to log on to your payment gateway's console to process the refund.

When you process a refund, use the refund endpoint to pass the refund amount. If you don't pass an amount, the refund is processed as Mark as refunded. For more information, see the Mark as Refunded section.

Each time a partial refund is triggered, the transaction.updated event is generated and updated with refunded.amount. The `order.updated` event is also triggered. The `order.refunded` event generates when the full amount is refunded.

#### Mark as Refunded

You can use your payment gateway's console to process a refund. Process the refund first in the payment gateway and then use the **Mark as Refunded** capability in Composable Commerce to complete the process.

When an order is **Marked as refunded**, the payment status `order.payment.status` is set to `refunded`. In this case, the `order.updated`, `transaction.updated` and `order.refunded` events are generated.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Update a shipping group for an order

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a shipping group for an order"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/orders/{orderID}/shipping-groups/{shippingGroupID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a shipping group for an order

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","required":true,"description":"The ID of the order","schema":{"type":"string"}},{"name":"shippingGroupID","in":"path","required":true,"description":"The ID of the shipping group","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters.","type":"string","maxLength":64},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"}}}},"title":"UpdateOrderShippingGroupRequest"},"example":{"data":{"type":"shipping_group","shipping_type":"express","tracking_reference":"TRACK456","address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"ACME Corp","line_1":"123 Main St","line_2":"Suite 100","city":"Portland","postcode":"97201","county":"Multnomah","country":"US","region":"Oregon","instructions":"Leave at front door"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Shipping group updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Shipping Group Response","type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"id":{"type":"string"},"relation":{"type":"string"},"cart_id":{"type":"string"},"order_id":{"type":"string"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","maxLength":64,"examples":["SG-12345"]},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"relationships":{"type":"object","properties":{"cart":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"order":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}},"discounts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"},"title":"Discounts"},"meta":{"type":"object","properties":{"shipping_display_price":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"base":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"fees":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"required":["total","base"],"title":"ShippingPriceResponse"},"total_display_price":{"description":"Order pricing information.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}},"required":["with_tax","without_tax","tax","discount","balance_owing","paid","authorized","without_discount","shipping","shipping_discount"],"title":"OrderPriceWrapperMeta"}},"title":"ShippingGroupMeta"}}},"included":{"type":"object","description":"Related objects that are included in the response when using the include query parameter.","properties":{"items":{"description":"Array of order items associated with this shipping group.","type":"array","items":{"title":"OrderItemResponse","type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["68bf8510-bebf-47b1-96ba-8a9930c7d928"]},"quantity":{"description":"The quantity of this item were ordered.","type":"number","examples":[1]},"product_id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["4e9c6098-9701-4839-a69c-54d8256d9012"]},"subscription_offering_id":{"description":"The unique identifier for the subscription offering for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["69a39623-e681-415e-83c0-e1281010c77d"]},"name":{"description":"The name of this order item.","type":"string","examples":["Product 123"]},"sku":{"description":"The SKU code for the order item.","type":"string","examples":["IFD-1"]},"location":{"description":"The stock location for this order item.","type":"string","readOnly":true},"unit_price":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"value":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"discounts":{"type":"array","items":{"title":"DiscountData","type":"object","properties":{"amount":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"code":{"type":"string"},"id":{"type":"string","format":"uuid","readOnly":true},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}}}},"links":{"type":"object"},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discounts":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$1.00"]},"constituents":{"type":"object","description":"Detailed breakdown of discount constituents by ID","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","description":"The discount amount"},"currency":{"type":"string","description":"The currency code"},"formatted":{"type":"string","description":"The formatted discount amount"}}}}}}},"original_price":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"type":"object","properties":{"cart_item":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this item.","type":"string","format":"uuid","readOnly":true,"examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}},"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.","type":"string","examples":["default"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","examples":["pim","legacy"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Component product ID","type":"string"},"type":{"description":"Component product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product metadata as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price information as a generic object","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the bundle product.","type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"custom_inputs":{"description":"Custom inputs for the order item as a generic object","type":"object","additionalProperties":true},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true},"shipping_group_id":{"description":"The shipping group ID for the order item","type":"string"},"promotion_source":{"description":"The promotion source for the order item","type":"string"},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"subscription_configuration":{"description":"Subscription configuration for the order item","type":"object","properties":{"plan":{"description":"Subscription plan details","type":"string"},"pricing_option":{"description":"Pricing option for the subscription","type":"string"}}}}}}},"additionalProperties":false},"errors":{"type":"array","description":"Array of validation or processing errors","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"ShippingGroupEntityResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"invalid_dates":{"value":{"errors":[{"status":400,"title":"Date Logic Discrepancy","detail":"The start date cannot occur after the end date"}]}},"fulfilled_order":{"value":{"errors":[{"status":400,"title":"Bad Request","detail":"Cannot update order shipping address because shipping status is fulfilled"}]}}}}}},"404":{"description":"Shipping group or order not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"status":404,"title":"Group not found","detail":"Group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for order [abc123]"}]}}}}}}
>
  
</StatusCodes>

---

## Update Cart Settings by Store ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Cart Settings by Store ID"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings/cart/{storeID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can modify the cart expiry settings to set it to any number of days up to 365. Any existing carts default to the expiry of 7 days. To update cart settings in Commerce Manager, see [Updating Cart setting](/docs/commerce-manager/settings/general-settings#updating-cart-settings).

With update cart settings endpoint, you can:

- Enable or disable custom discounts by setting the `custom_discounts_enabled` field to `true`. This allows you to activate your custom discounts from external services. By default, this setting is determined by the cart settings configured for the store.
- Enable or disable the use of rule promotions within the cart. You can apply this setting either at the store level using the update cart setting endpoint or individually to a specific cart using the [update a cart](/docs/api/carts/update-a-cart) endpoint.
- Enable or disable deferred inventory checks by setting `defer_inventory_check` to `true`. When set, stock levels are not verified for products in a cart until checkout.
- Control whether admins can see all carts or only shopper-associated carts by setting `show_all_carts` to `true` or `false`.
- Enable or disable location-based item separation by setting `separate_items_by_location` to `true`. When enabled, cart items with the same SKU but different locations are kept as separate line items instead of being merged.

:::note

Custom discounts and rule promotions can both be enabled for a store at the same time, for example, while transitioning from one promotion system to the other. However, an individual cart can only contain one type of discount at a time. A cart that contains custom discounts rejects Elastic Path promotions, and a cart that contains Elastic Path promotions rejects custom discounts, until the existing discounts are removed.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"storeID","in":"path","description":"The store ID.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you're sending. Set this value to `settings`.","example":"settings"},"id":{"type":"string","description":"The unique identifier for the cart settings.","readOnly":true,"example":"15419118-44ce-5343-8ff6-574daf52bc6b"},"cart_expiry_days":{"type":"integer","description":"Indicates the number of days before a cart expires.","example":25},"discounts":{"type":"object","properties":{"custom_discounts_enabled":{"description":"When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false},"use_rule_promotions":{"description":"When set to `true`, this parameter allows the cart to use rule promotions.","type":"boolean","example":false}}},"inventories":{"type":"object","properties":{"defer_inventory_check":{"description":"When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false}}},"items":{"type":"object","properties":{"separate_items_by_location":{"description":"When `true`, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When `false` (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","example":false}}},"show_all_carts":{"description":"When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts).\n\nFor new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility.\n","type":"boolean","example":true}},"required":["type"]}},"title":"SettingsCart"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you're sending. Set this value to `settings`.","example":"settings"},"id":{"type":"string","description":"The unique identifier for the cart settings.","readOnly":true,"example":"15419118-44ce-5343-8ff6-574daf52bc6b"},"cart_expiry_days":{"type":"integer","description":"Indicates the number of days before a cart expires.","example":25},"discounts":{"type":"object","properties":{"custom_discounts_enabled":{"description":"When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false},"use_rule_promotions":{"description":"When set to `true`, this parameter allows the cart to use rule promotions.","type":"boolean","example":false}}},"inventories":{"type":"object","properties":{"defer_inventory_check":{"description":"When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false}}},"items":{"type":"object","properties":{"separate_items_by_location":{"description":"When `true`, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When `false` (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","example":false}}},"show_all_carts":{"description":"When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts).\n\nFor new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility.\n","type":"boolean","example":true}},"required":["type"]}},"title":"SettingsCart"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Update Cart Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Cart Settings"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings/cart"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can modify the cart expiry settings to set it to any number of days up to 365. Any existing carts default to the expiry of 7 days. To update cart settings in Commerce Manager, see [Updating Cart setting](/docs/commerce-manager/settings/general-settings#updating-cart-settings).

With update cart settings endpoint, you can:

- Enable or disable custom discounts by setting the `custom_discounts_enabled` field to `true`. This allows you to activate your custom discounts from external services. By default, this setting is determined by the cart settings configured for the store.
- Enable or disable the use of rule promotions within the cart. You can apply this setting either at the store level using the update cart setting endpoint or individually to a specific cart using the [update a cart](/docs/api/carts/update-a-cart) endpoint.
- Enable or disable deferred inventory checks by setting `defer_inventory_check` to `true`. When set, stock levels are not verified for products in a cart until checkout.
- Control whether admins can see all carts or only shopper-associated carts by setting `show_all_carts` to `true` or `false`.
- Enable or disable location-based item separation by setting `separate_items_by_location` to `true`. When enabled, cart items with the same SKU but different locations are kept as separate line items instead of being merged.

:::note

Custom discounts and rule promotions can both be enabled for a store at the same time, for example, while transitioning from one promotion system to the other. However, an individual cart can only contain one type of discount at a time. A cart that contains custom discounts rejects Elastic Path promotions, and a cart that contains Elastic Path promotions rejects custom discounts, until the existing discounts are removed.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you're sending. Set this value to `settings`.","example":"settings"},"id":{"type":"string","description":"The unique identifier for the cart settings.","readOnly":true,"example":"15419118-44ce-5343-8ff6-574daf52bc6b"},"cart_expiry_days":{"type":"integer","description":"Indicates the number of days before a cart expires.","example":25},"discounts":{"type":"object","properties":{"custom_discounts_enabled":{"description":"When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false},"use_rule_promotions":{"description":"When set to `true`, this parameter allows the cart to use rule promotions.","type":"boolean","example":false}}},"inventories":{"type":"object","properties":{"defer_inventory_check":{"description":"When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false}}},"items":{"type":"object","properties":{"separate_items_by_location":{"description":"When `true`, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When `false` (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","example":false}}},"show_all_carts":{"description":"When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts).\n\nFor new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility.\n","type":"boolean","example":true}},"required":["type"]}},"title":"SettingsCart"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you're sending. Set this value to `settings`.","example":"settings"},"id":{"type":"string","description":"The unique identifier for the cart settings.","readOnly":true,"example":"15419118-44ce-5343-8ff6-574daf52bc6b"},"cart_expiry_days":{"type":"integer","description":"Indicates the number of days before a cart expires.","example":25},"discounts":{"type":"object","properties":{"custom_discounts_enabled":{"description":"When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false},"use_rule_promotions":{"description":"When set to `true`, this parameter allows the cart to use rule promotions.","type":"boolean","example":false}}},"inventories":{"type":"object","properties":{"defer_inventory_check":{"description":"When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected.","type":"boolean","example":false}}},"items":{"type":"object","properties":{"separate_items_by_location":{"description":"When `true`, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When `false` (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","example":false}}},"show_all_carts":{"description":"When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts).\n\nFor new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility.\n","type":"boolean","example":true}},"required":["type"]}},"title":"SettingsCart"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Refund a Transaction

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Refund a Transaction"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/orders/{orderID}/transactions/{transactionID}/refund"}
  context={"endpoint"}
>
  
</MethodEndpoint>

There are two ways to refund; through your payment gateway and mark it refunded in Commerce Manager, or directly through Commerce Manager or API.

* Mark as Refunded: You can manually mark a transaction as refunded. Before you can mark the order as refunded, you need to handle the actual refund on your side with your payment provider. Mark as Refunded is a full refund made to the transaction.
* Refund through Composable Commerce: You can process a full or partial refund to a supported payment provider directly from Commerce Manager or API by providing the refund amount. When you start the refund process, the request is directly sent to the payment gateway.

:::caution

If you use manual gateway for partial or full refund, you need to handle the actual refund on your side with your payment provider.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The UUID of the order.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"transactionID","in":"path","description":"The UUID of the transaction you want to refund.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"OrdersTransactionsRefundRequest","type":"object","properties":{"data":{"type":"object","properties":{"amount":{"description":"The amount value to be refunded. If this field is not provided, it will be considered as manual refund (Mark as Refunded) and the refund process must be manually handled via payment provider. If the amount value is same as payment value, then it will be treated as a full refund and sent to the payment provider to process refund automatically.","type":"number","examples":[1000]},"options":{"type":"object","properties":{"note":{"description":"Provides comments about the refund. It is used by PayPal Express.","type":"string"}}}}}}}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"TransactionResponse","properties":{"id":{"description":"The ID of the transaction.","type":"string","format":"uuid","readOnly":true},"reference":{"description":"The payment gateway reference.","type":"string","examples":["manual"]},"name":{"description":"A custom name associated with the payment method.","type":"string","examples":["payment method name"]},"custom_reference":{"description":"A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field.","type":"string","examples":["custom reference"]},"gateway":{"description":"The name of the payment gateway used.","type":"string","enum":["adyen","authorize_net","braintree","card_connect","cyber_source","elastic_path_payments_stripe","manual","paypal_express_checkout","stripe","stripe_payment_intents","stripe_platform_account"]},"amount":{"description":"The amount for this transaction.","type":"number","examples":[10000]},"refunded_amount":{"description":"The refunded amount.","type":"number","examples":[0]},"currency":{"description":"The transaction currency.","type":"string","examples":["USD"]},"transaction_type":{"description":"The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`.","type":"string","enum":["purchase","authorize","capture","refund"]},"type":{"description":"The type of object being returned.","type":"string"},"status":{"description":"The status provided by the gateway for this transaction, such as `complete` or `failed`.","type":"string","examples":["complete"]},"payment_details":{"description":"Payment gateway specific details.","type":"object","properties":{"detailed_status":{"description":"Detailed status from the payment gateway.","type":"string"}}},"failure_details":{"description":"Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information.","title":"FailureDetails","type":"object","properties":{"code":{"description":"Machine-readable failure or error code from the payment gateway.","type":"string","examples":["2"]},"reason":{"description":"Human-readable failure reason or error message from the payment gateway.","type":"string","examples":["This transaction has been declined."]}}},"payment_intent":{"description":"Payment intent details.","type":"object","additionalProperties":true},"capture_mechanism":{"description":"The mechanism used for capturing the transaction.","type":"string","enum":["automatic","manual"]},"refund_mechanism":{"description":"The mechanism used for refunding the transaction.","type":"string","enum":["automatic","manual"]},"client_parameters":{"description":"Client-specific parameters for payment processing.","type":"object","properties":{"redirect_url":{"description":"URL to redirect the client after payment.","type":"string"},"secret":{"description":"Client secret for payment processing.","type":"string"},"token":{"description":"Client token for payment processing.","type":"string"}}},"next_actions":{"description":"Array of next actions for the transaction.","type":"array","items":{"type":"string"}},"relationships":{"type":"object","properties":{"order":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"Represents the type of the object being returned. It is always `order`.","type":"string","examples":["order"]},"id":{"description":"The ID of the order.","type":"string","format":"uuid","examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}}}},"meta":{"type":"object","properties":{"display_price":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"display_refunded_amount":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}}}}},"required":["data"],"title":"TransactionEntityResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Validation error","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Transaction cannot be refunded in its current state\",\n      \"status\": \"422\",\n      \"title\": \"Unprocessable Entity\"\n    }\n  ]\n}\n"}}}}}}}}
>
  
</StatusCodes>

---

## Tax Items

Taxes differ by country and can differ within the country by region, state, or province. Each jurisdiction has a unique tax code and rate. If your store serves many jurisdictions, integrate a third-party tax generator to manage taxes. If your store serves a few jurisdictions, you can use the API to define the tax codes and rates in Composable Commerce.

Taxes are calculated after all promotional discounts have been applied. When calculating taxes on a cart or order, you can choose from the following methods for calculating taxes:

  - Simple calculation method: Taxes are calculated at the unit level and are rounded to the nearest penny for the unit.
  - Line calculation method: Default. Taxes are calculated at the line level and are rounded to the nearest penny for the line.
    For more information about calculation methods, see [Calculate cart and order totals](/guides/How-To/Carts/calculate-totals).

Tax values can be either `rate` or `amount`.
  - `rate` - Represents the tax as a percentage in decimal form.
  - `amount` - Represents a tax amount.

:::note
Tax items can be added and removed using [client_credentials access tokens](/docs/api/authentication/create-an-access-token). Only administrators with `client-credentials` access tokens are able to manage tax items.
:::

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Update a Cart Item

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Cart Item"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartID}/items/{cartitemID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can easily update a cart item. A successful update returns the cart items.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"A unique identifier of the cart that you created.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"A unique identifier of the cart item.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Update Carts Items","type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type of the cart item.","type":"string","const":"cart_item"},"id":{"description":"The unique identifier of the cart item.","type":"string","format":"uuid","examples":["{{cartitemID}}"]},"quantity":{"description":"The amount of products to add to cart.","type":"number","examples":[2]},"custom_inputs":{"description":"The custom text to be added to a product.","type":"object"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"shipping_group_id":{"description":"The unique identifier of the shipping group to be added to the cart.","type":"string","format":"uuid","examples":["900ab9c1-4b39-43fe-b080-0dc2806065d9"]}}}}}]},"examples":{"Update Cart Item":{"value":{"data":{"type":"cart_item","id":"76746981-f63a-45f4-ba9e-59773d89dc2e","custom_inputs":{"personalization":"My personal message"},"quantity":2}}},"Add Item with Shipping Group ID":{"value":{"data":{"type":"cart_item","id":"76746981-f63a-45f4-ba9e-59773d89dc2e","shipping_group_id":"eb063818-939a-458f-97a4-2601c0c2b445"}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Cart Item Response","type":"object","properties":{"id":{"description":"The unique identifier for the cart item.","type":"string","format":"uuid","readOnly":true,"examples":["4649fbb3-b8ee-4883-82c9-49a3d5fbacf1"]},"type":{"description":"The type of cart item.","type":"string","readOnly":true,"enum":["cart_item","custom_item","subscription_item","promotion_item"],"examples":["cart_item"]},"product_id":{"description":"The unique ID of the product (for cart_item type).","type":"string","format":"uuid","readOnly":true,"examples":["55cda543-f9d7-42a4-b40a-665f2e4ff7c5"]},"promotion_id":{"description":"The unique ID of the promotion (for promotion_item type).","type":"string","format":"uuid","readOnly":true,"examples":["9993387e-93ab-468f-bba9-cf13882dc52d"]},"subscription_offering_id":{"description":"The unique ID of the subscription offering for subscription items.","type":"string","format":"uuid","readOnly":true,"examples":["9c13669e-29d7-42ea-bc95-1b32399adb9d"]},"name":{"description":"The name of this item","type":"string","readOnly":true,"examples":["shirt"]},"description":{"description":"A description of the cart item.","type":"string","readOnly":true,"examples":["T-shirt."]},"sku":{"description":"The SKU of the cart item.","type":"string","readOnly":true,"examples":["sample-sku"]},"slug":{"description":"The slug of the cart item.","type":"string","readOnly":true,"examples":["sample-product"]},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if catalog_source=pim is set.","type":"string","readOnly":true,"format":"uuid","examples":["11d3f9d2-c99b-472c-96c3-51842333daea"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","readOnly":true,"examples":["pim"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","readOnly":true,"properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Product ID","type":"string"},"type":{"description":"Product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product meta information as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the cart item for bundle products.","type":"object","readOnly":true,"additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"image":{"type":"object","readOnly":true,"properties":{"mime_type":{"description":"The MIME type for the uploaded file.","type":"string","readOnly":true,"examples":["image/png"]},"file_name":{"description":"The name of the image file that was uploaded.","type":"string","readOnly":true,"examples":["shirt-trans.png"]},"href":{"description":"The link to the image.","type":"string","readOnly":true,"examples":["https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/7cc08cbb-256e-4271-9b01-d03a9fac9f0a.png"]}}},"quantity":{"description":"The quantity of the cart item.","type":"integer","readOnly":true,"examples":[1]},"auto_add_quantity":{"description":"The quantity automatically added (for gift items).","type":"integer","readOnly":true},"manage_stock":{"description":"Whether or not the quantity of the item will be checked against inventory.","type":"boolean","readOnly":true,"examples":[true]},"unit_price":{"description":"The unit price of the item.","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"value":{"description":"The total price of the item (i.e., unit * quantity).","readOnly":true,"title":"Order Price Data","type":"object","properties":{"amount":{"description":"The amount for this item as an integer.","type":"number","readOnly":true,"examples":[10000]},"currency":{"description":"The currency this item was added to the cart as.","type":"string","readOnly":true,"examples":["USD"]},"includes_tax":{"description":"Whether or not this price is tax inclusive.","type":"boolean","readOnly":true,"examples":[false]}}},"discounts":{"description":"Array of discounts applied to the cart item.","type":"array","readOnly":true,"items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"}},"custom_inputs":{"description":"Custom inputs for personalized products.","type":"object","readOnly":true,"additionalProperties":true,"examples":[{"tshirt_front":"John Doe","tshirt_back":"My Custom Text"}]},"subscription_configuration":{"description":"Configuration for subscription items.","type":"object","readOnly":true,"properties":{"plan":{"description":"The subscription plan ID.","type":"string"},"pricing_option":{"description":"The subscription pricing option ID.","type":"string"}}},"links":{"type":"object","readOnly":true,"properties":{"product":{"description":"A URL related to the resource.","type":"string","examples":["https://useast.api.elasticpath.com/products/9eda5ba0-4f4a-4074-8547-ccb05d1b5981"]},"subscription_offering":{"description":"A URL related to the subscription offering resource.","type":"string"}}},"meta":{"type":"object","readOnly":true,"properties":{"display_price":{"type":"object","properties":{"with_tax":{"description":"The amount of this item after discounts and taxes are applied.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_tax":{"description":"The amount of this item after discounts are applied and before taxes.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"tax":{"description":"The amount of taxes applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"discount":{"description":"The amount of the discount applied to this item.","title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"without_discount":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}}},"original_price":{"title":"CartItemFormattedPriceData","type":"object","properties":{"unit":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The amount per each single unit."},"value":{"type":"object","allOf":[{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}],"description":"The total amount of the item (i.e., unit * quantity)."}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."},"discounts":{"description":"Detailed discount information.","type":"object","additionalProperties":{"type":"object","required":["amount","currency","formatted"],"properties":{"amount":{"description":"The discount amount.","type":"integer","examples":[100]},"currency":{"description":"The currency code.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted discount amount.","type":"string","examples":["$1.00"]},"constituents":{"description":"The discount constituents.","type":"object","additionalProperties":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"description":"Relationships to other resources.","readOnly":true,"type":"object","properties":{"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"custom_discounts":{"description":"Related custom discounts.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"shipping_group_id":{"description":"The shipping group ID for this item.","type":"string","readOnly":true,"examples":["eb063818-939a-458f-97a4-2601c0c2b445"]},"promotion_source":{"description":"The source of the promotion (for promotion items).","type":"string","readOnly":true,"enum":["rule-promotion"],"examples":["rule-promotion"]},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"location":{"description":"The stock location for this item.","type":"string","readOnly":true,"examples":["warehouse-1"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true}}}},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"type":"object","properties":{"automatic":{"type":"boolean"},"description":{"type":"string"},"end":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"promotion_type":{"type":"string"},"promotion_source":{"type":"string","description":"The source of the promotion"},"start":{"type":"string","format":"date-time"},"type":{"type":"string","const":"promotion"}}}},"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}}}},"meta":{"type":"object","description":"Additional meta information about the cart items collection.","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"balance_owing":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"messages":{"type":"array","description":"Optional array of informational messages that provide feedback about operations performed on the cart items, such as promotions added or discounts applied. This field is only present when there are relevant messages to display.\n","items":{"type":"object","properties":{"source":{"type":"object","description":"Identifies the cart item that triggered this message","properties":{"type":{"type":"string","description":"The type of the source item"},"id":{"type":"string","description":"The unique identifier of the source item"},"code":{"type":"string","description":"The promotion code (present when source type is promotion)"}},"required":["type","id"]},"title":{"type":"string","description":"A short descriptive title for the message"},"description":{"type":"string","description":"A detailed description of the message"}},"required":["title","description"]}},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"},"auto_add":{"type":"boolean","description":"Whether this promotion should be automatically added"},"targets":{"description":"Array of promotion targets (alternative structure)","type":"array","items":{"type":"object","properties":{"cart_item_id":{"type":"string","description":"The cart item ID for this target"},"quantity":{"type":"integer","description":"The quantity for this target"},"skus":{"type":"array","description":"Array of SKU codes for this target","items":{"type":"string"}}}}}}}}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"required":["data"],"title":"CartItemCollectionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Cart Currency Mismatch","value":{"errors":[{"detail":"The existing shipping group uses USD, cannot add this shipping group to a cart item with currency GBP","meta":{"item_ids":["51197fc0-e217-4f69-a769-b3887f58cfff"],"shipping_group_id":"fcb87ec9-a7fb-48c2-bcd9-2151b64e1abc"},"status":404,"title":"Cart Currency Mismatch"}]}}}}}},"403":{"description":"Unauthorized call","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"No permissions to use custom attributes","value":{"errors":[{"detail":"No permissions to fulfill this request with cart item custom_attributes","meta":{"id":"76746981-f63a-45f4-ba9e-59773d89dc2e"},"status":403,"title":"Unauthorised call"}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"default":{"summary":"Not Found","value":{"errors":[{"detail":"Shipping groups not found for this cart.  Please verify the shipping groups exists for this cart and are not already associated with orders.","meta":{"cart_id":"a-cart-id","shipping_group_ids":["fcb87ec9-a7fb-48c2-bcd9-2151b64e1abc"]},"status":404,"title":"Shipping groups not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Cart"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates cart properties for the specified cartID.

You can update a cart to specify custom discounts. You can enable custom discounts when the `discount_settings.custom_discounts_enabled` field is set to `true`. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).

You can also create a cart when inventory checks are not performed until checkout by setting the `inventory_settings.defer_inventory_check` field to `true`. Again the default is set from cart discount settings for the store. See [Update Cart Settings](/docs/api/carts/put-v-2-settings-cart).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of a cart created by you.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"title":"CartsRequest","type":"object","properties":{"data":{"type":"object","properties":{"description":{"type":"string","description":"The cart description.","examples":["cart description"]},"discount_settings":{"title":"DiscountSettings","type":"object","properties":{"custom_discounts_enabled":{"description":"This parameter enables custom discounts for a cart. When set to true and `use_rule_promotions` is not enabled, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).","type":"boolean","examples":[false]},"use_rule_promotions":{"description":"When set to true, this parameter allows the cart to use rule promotions. You can enable this setting together with `custom_discounts_enabled`, for example, while transitioning between promotion systems. However, an individual cart can only contain one type of discount at a time.","type":"boolean","examples":[false]}}},"inventory_settings":{"title":"InventorySettings","type":"object","properties":{"defer_inventory_check":{"description":"This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout","type":"boolean","examples":[false]}}},"item_settings":{"title":"ItemSettings","type":"object","properties":{"separate_items_by_location":{"description":"When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","examples":[false]}}},"name":{"description":"The cart name provided by the shopper. A cart name must contain 1 to 255 characters. You cannot use whitespace characters, but special characters are permitted. For more information, see the [Safe Characters](/guides/Getting-Started/safe-characters) section.","type":"string","examples":["my cart name"]},"contact":{"title":"CartContact","type":"object","properties":{"email":{"description":"The email address attached to a cart.","type":"string","format":"email","examples":["tester@email.com"]}}},"snapshot_date":{"description":"This optional parameter sets a reference date for the cart. If this parameter is set, it allows the cart to act as one that might occur on that specified date. For example, such future carts might acquire future-enabled discounts, allowing users to test and validate future interactions with carts. The snapshot_date must be in the format 2026-02-21T15:07:25Z. By default, this parameter is left empty.","type":"string","examples":["2026-09-10T00:12:00Z"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"payment_intent_id":{"description":"To remove the Stripe payment intent from a cart, pass the empty value in the `payment_intent_id` field.  You must use an empty value for this field. You cannot use this endpoint to directly update the cart to use an existing Payment Intent.","type":"string","examples":[""]}}}}},"examples":{"Update a Cart":{"value":{"data":{"name":"my cart","description":"my first cart","discount_settings":{"custom_discounts_enabled":false,"use_rule_promotions":true},"snapshot_date":"2026-09-10T00:12:00Z"}}},"Remove Payment Intent from a Cart":{"value":{"data":{"payment_intent_id":""}}},"Update Cart with Custom Attributes":{"value":{"data":{"name":"cart with custom attribute","description":"cart description","custom_attributes":{"affiliate_link":{"type":"string","value":"https://site.com?tag=influencer04-21"}}}}},"Update Cart with Contact Email":{"value":{"data":{"name":"cart with contact email","description":"cart description","contact":{"email":"tester@email.com"}}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"CartResponse","allOf":[{"title":"BaseCartResponse","type":"object","properties":{"id":{"description":"The unique identifier for the cart. Use SDK or create it yourself.","type":"string"},"name":{"description":"The name of this cart.","type":"string","examples":["cart name"]},"description":{"description":"A description of the cart.","type":"string","examples":["cart description"]},"contact":{"title":"CartContact","type":"object","properties":{"email":{"description":"The email address attached to a cart.","type":"string","format":"email","examples":["tester@email.com"]}}},"discount_settings":{"title":"DiscountSettings","type":"object","properties":{"custom_discounts_enabled":{"description":"This parameter enables custom discounts for a cart. When set to true and `use_rule_promotions` is not enabled, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).","type":"boolean","examples":[false]},"use_rule_promotions":{"description":"When set to true, this parameter allows the cart to use rule promotions. You can enable this setting together with `custom_discounts_enabled`, for example, while transitioning between promotion systems. However, an individual cart can only contain one type of discount at a time.","type":"boolean","examples":[false]}}},"inventory_settings":{"title":"InventorySettings","type":"object","properties":{"defer_inventory_check":{"description":"This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout","type":"boolean","examples":[false]}}},"item_settings":{"title":"ItemSettings","type":"object","properties":{"separate_items_by_location":{"description":"When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","examples":[false]}}},"payment_intent_id":{"description":"Stripe-assigned unique identifier for the linked Payment Intent","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"snapshot_date":{"description":"The snapshot date for the cart.","type":"string","format":"date-time"},"links":{"type":"object","properties":{"self":{"description":"A link to that specific resource.","type":"string"}},"examples":["https://useast.api.elasticpath.com/v2/carts/1"]},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"}}}}}},"relationships":{"type":"object","properties":{"customers":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"items":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}]}},"required":["data"]}]},"accounts":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}}},{"type":"object","properties":{"type":{"description":"The type of object being returned.","type":"string","const":"cart"}}}]},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}},"meta":{"type":"object","description":"Additional metadata for the cart response.","properties":{"payment_intent":{"type":"object","description":"Payment intent details with nested structure including status and other Stripe payment intent fields","additionalProperties":true}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"CartEntityResponse"}}}},"403":{"description":"Unauthorized call","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"}}}},"422":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}}}}}
>
  
</StatusCodes>

---

## Update a Tax Item

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Tax Item"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/taxes/{taxitemID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to update a tax item. To change tax value from `rate` to `amount`, set `rate` to `null`, then set `amount` value and vice versa.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"The unique identifier of the cart item.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"taxitemID","in":"path","description":"The unique identifier of the tax item.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"updateRateTaxItem":{"summary":"Update a tax item using rate","value":{"data":{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.15}}},"updateAmountTaxItem":{"summary":"Update a tax item using amount","value":{"data":{"type":"tax_item","code":"GST","jurisdiction":"AU","name":"Goods and Services Tax","amount":1500}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"updatedRateTaxItem":{"summary":"Updated tax item (rate)","value":{"data":{"id":"662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9","type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.15}}}}}}}}}
>
  
</StatusCodes>

---

## Update an Order

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Order"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/orders/{orderID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can only update custom data, `shipping`, `shipping_address`, and status of orders. All other settings in the order object are immutable.

 This endpoint allows you to:

- **Update an order number and external reference**: You can update an existing order that does not have an `order_number` and `external_ref`, modify the `order_number` and `external_ref` values, or remove them by passing an empty value in the `order_number` and `external_ref` fields.
- **Cancel an order**: You can cancel an order only if it has not been fulfilled.
- **Fulfill an order**: You can fulfill a paid order only.

:::caution

You can update `shipping`, `shipping_address`, and status of an order only if the order is not fulfilled. You can use the refund API to refund an order only if the payment status is `paid`. Canceling an order does not automatically refund a payment. You must refund the orders manually.

:::

:::note

- This request is only accessible to client credentials token users with Seller Admin role.
- Non client credentials token users cannot access this endpoint. See [Permissions](/docs/authentication/tokens/permissions).
- The `order_number` will appear as the invoice number in Authorize.net transactions.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"orderID","in":"path","description":"The unique identifier of the order.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"OrdersUpdateRequest","type":"object","properties":{"data":{"oneOf":[{"title":"OrdersAddressData","type":"object","required":["type","shipping_address"],"properties":{"type":{"description":"The type of the resource. You must use \"order\".","type":"string","examples":["order"]},"order_number":{"description":"Specifies a user-managed, optional field used as an alternative to the existing order_id. If provided, the order-number will be sent to Authorize.net instead of the order_id, and will appear as the invoice number in Authorize.net transactions.","type":"string","examples":[1234]},"external_ref":{"description":"Represents an optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","examples":["external_order_123"]},"shipping_address":{"type":"object","properties":{"first_name":{"description":"Specifies the first name of the address holder.","type":"string","examples":["James"]},"last_name":{"description":"Specifies the last name of the address holder.","type":"string","examples":["Doe"]},"phone_number":{"description":"Specifies the phone number of the address holder.","type":"string","examples":[5558679305]},"company_name":{"description":"Specifies the company name.","type":"string","examples":["company name"]},"line_1":{"description":"Specifies the first line of the address.","type":"string","examples":["1234 Disney Drive"]},"line_2":{"description":"Specifies the second line of the address.","type":"string","examples":["Disney Resort"]},"line_3":{"description":"Specifies the third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"Specifies the name of the city in the shipping address.","type":"string","examples":["Anaheim"]},"county":{"description":"Specifies the county of the shipping address.","type":"string","examples":["Orange"]},"region":{"description":"Specifies the state, province, or region of the shipping address.","type":"string","examples":["CA"]},"postcode":{"description":"Specifies the postcode or ZIP code of the address.","type":"string","examples":[92802]},"country":{"description":"Specifies the country in the shipping address.","type":"string","examples":["US"]},"instructions":{"description":"Specifies any instructions provided with the shipping address.","type":"string","examples":["Buzzer 10233"]}}}}},{"title":"OrdersCancelData","type":"object","required":["type","status"],"properties":{"status":{"description":"The status of the order. You can only update the status to `cancelled`.","type":"string","examples":["cancelled"]},"type":{"description":"The type of the resource. You must use order.","type":"string","examples":["order"]},"external_ref":{"description":"Represents an optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","examples":["external_order_123"]}}},{"title":"OrdersFulfilledData","type":"object","required":["type","shipping"],"properties":{"shipping":{"description":"The shipping status of the order. You can only update the shipping status to `fulfilled`.","type":"string","examples":["fulfilled"]},"type":{"description":"The type of the resource. You must use order.","type":"string","examples":["order"]},"external_ref":{"description":"Represents an optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","examples":["external_order_123"]}}}]}}}]},"examples":{"CancelAnOrder":{"summary":"Cancel an Order","value":{"data":{"type":"order","status":"cancelled"}}},"FulfillAnOrder":{"summary":"Fulfill an Order by ID. You can fulfill a paid order only.","value":{"data":{"type":"order","shipping":"fulfilled"}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"title":"OrderEntityResponse","type":"object","properties":{"data":{"title":"OrderResponse","type":"object","properties":{"type":{"description":"Specifies the type of object being returned. You must use `order`.","type":"string","const":"order"},"order_number":{"description":"Specifies a user-managed, optional field used as an alternative to the existing `order_id`. If provided, the order-number will be sent to Authorize.net instead of the `order_id`, and will appear as the invoice number in Authorize.net transactions.","type":"string","examples":[1234]},"external_ref":{"description":"An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","examples":["e-123456789"]},"id":{"description":"Specifies the unique identifier of the order.","type":"string","format":"uuid","readOnly":true,"examples":["aa854b8f-5930-476d-951a-e9b9cfbdefb1"]},"status":{"description":"Specifies the status of the order, such as `incomplete`, `complete`, `processing`, or `cancelled`.","type":"string","enum":["complete","incomplete","cancelled","processing"]},"payment":{"description":"Specifies the status of the payment, such as `unpaid`, `authorized`, `paid`, or `refunded`.","type":"string","enum":["authorized","paid","unpaid","refunded","partially_paid","partially_authorized"]},"shipping":{"description":"Specifies the status of the shipment, such as `fulfilled` or `unfulfilled`.","type":"string","enum":["unfulfilled","fulfilled"]},"anonymized":{"description":"Specifies if the order is anonymized.","type":"boolean","examples":[false]},"payment_intent_id":{"description":"Stripe Payment Intent ID.  Please see Stripe's Payment Intent [documentation](https://docs.stripe.com/api/payment_intents) for more information on Payment Intents.","type":"string","examples":["pi_3MtwBwLkdIwHu7ix28a3tqPa"]},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"links":{"type":"object"},"meta":{"title":"OrderMeta","type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this order was created.","type":"string"},"updated_at":{"description":"The date this order was last updated.","type":"string"},"fully_paid_at":{"description":"The date this order was fully paid. Only present for orders with payment status 'paid'.","type":"string"}},"title":"OrderTimestamps"},"display_price":{"description":"Order pricing information including amounts, tax, discounts, and payment details.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}}},"is_manual":{"description":"Specifies if the order was created manually.","type":"boolean"}}},"billing_address":{"title":"BillingAddress","description":"Billing address information. You must specify at least one of region (state/province) or county.\n","anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}],"examples":[{"first_name":"John","last_name":"Doe","company_name":"John Doe Enterprises","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB"}]},"contact":{"title":"Contact","type":"object","properties":{"email":{"description":"The email address of the contact.","type":"string","examples":["johndoe@email.com"]},"name":{"description":"The name of the contact.","type":"string","examples":["John Doe"]}}},"customer":{"title":"Customer","type":"object","properties":{"name":{"description":"The name of the customer.","type":"string","examples":["John Doe"]},"email":{"description":"The email address of the customer.","type":"string","format":"email","examples":["john.doe@example.com"]},"id":{"description":"The unique identifier of the customer.","type":"string","format":"uuid","examples":["e5a0d684-a4af-4919-a348-f66b0b4955e0"]}}},"shipping_address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"relationships":{"type":"object","properties":{"items":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"customer":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"account_member":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"store":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}},"included":{"description":"Optional included data such as order items, tax items, custom discounts, and promotions.\n","type":"object","properties":{"items":{"description":"Array of order items included in the response.","type":"array","items":{"title":"OrderItemResponse","type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["68bf8510-bebf-47b1-96ba-8a9930c7d928"]},"quantity":{"description":"The quantity of this item were ordered.","type":"number","examples":[1]},"product_id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["4e9c6098-9701-4839-a69c-54d8256d9012"]},"subscription_offering_id":{"description":"The unique identifier for the subscription offering for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["69a39623-e681-415e-83c0-e1281010c77d"]},"name":{"description":"The name of this order item.","type":"string","examples":["Product 123"]},"sku":{"description":"The SKU code for the order item.","type":"string","examples":["IFD-1"]},"location":{"description":"The stock location for this order item.","type":"string","readOnly":true},"unit_price":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"value":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"discounts":{"type":"array","items":{"title":"DiscountData","type":"object","properties":{"amount":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"code":{"type":"string"},"id":{"type":"string","format":"uuid","readOnly":true},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}}}},"links":{"type":"object"},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discounts":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$1.00"]},"constituents":{"type":"object","description":"Detailed breakdown of discount constituents by ID","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","description":"The discount amount"},"currency":{"type":"string","description":"The currency code"},"formatted":{"type":"string","description":"The formatted discount amount"}}}}}}},"original_price":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"type":"object","properties":{"cart_item":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this item.","type":"string","format":"uuid","readOnly":true,"examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}},"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.","type":"string","examples":["default"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","examples":["pim","legacy"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Component product ID","type":"string"},"type":{"description":"Component product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product metadata as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price information as a generic object","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the bundle product.","type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"custom_inputs":{"description":"Custom inputs for the order item as a generic object","type":"object","additionalProperties":true},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true},"shipping_group_id":{"description":"The shipping group ID for the order item","type":"string"},"promotion_source":{"description":"The promotion source for the order item","type":"string"},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"subscription_configuration":{"description":"Subscription configuration for the order item","type":"object","properties":{"plan":{"description":"Subscription plan details","type":"string"},"pricing_option":{"description":"Pricing option for the subscription","type":"string"}}}}}},"tax_items":{"description":"Array of tax items included in the response.","type":"array","items":{"title":"TaxItemResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"Specifies the UUID of the tax item.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"jurisdiction":{"description":"The jurisdiction for the tax item.","type":"string","examples":["US-CA"]},"code":{"description":"The tax code for the tax item.","type":"string","examples":["CA_SALES_TAX"]},"name":{"description":"The name of the tax item.","type":"string","examples":["California Sales Tax"]},"rate":{"description":"The tax rate as a decimal (e.g., 0.085 for 8.5%).","type":"number","format":"float","examples":[0.085]},"amount":{"description":"The tax amount in the smallest currency unit.","type":"integer","examples":[850]}}}},"custom_discounts":{"description":"Array of custom discounts included in the response.","type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"description":"Array of promotions included in the response.","type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Bad Request","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Request could not be processed\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse","examples":{"default":{"summary":"Validation error","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Order cannot be updated in its current state\",\n      \"status\": \"422\",\n      \"title\": \"Unprocessable Entity\"\n    }\n  ]\n}\n"}}}}}}}}
>
  
</StatusCodes>

---

## Update a Payment Intent on a Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Payment Intent on a Cart"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartID}/payments/{paymentIntentID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates the payment information for a specific payment intent on a cart.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"paymentIntentID","in":"path","description":"The unique identifier of the payment intent.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"title":"Cart Payment Update","type":"object","required":["data"],"properties":{"data":{"type":"object","required":["gateway","method","payment_method_types","amount"],"properties":{"gateway":{"type":"string"},"method":{"type":"string"},"payment_method_types":{"type":"array","items":{"type":"string"}},"amount":{"type":"integer"},"options":{"type":"object"}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Payment updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"CartResponse","allOf":[{"title":"BaseCartResponse","type":"object","properties":{"id":{"description":"The unique identifier for the cart. Use SDK or create it yourself.","type":"string"},"name":{"description":"The name of this cart.","type":"string","examples":["cart name"]},"description":{"description":"A description of the cart.","type":"string","examples":["cart description"]},"contact":{"title":"CartContact","type":"object","properties":{"email":{"description":"The email address attached to a cart.","type":"string","format":"email","examples":["tester@email.com"]}}},"discount_settings":{"title":"DiscountSettings","type":"object","properties":{"custom_discounts_enabled":{"description":"This parameter enables custom discounts for a cart. When set to true and `use_rule_promotions` is not enabled, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).","type":"boolean","examples":[false]},"use_rule_promotions":{"description":"When set to true, this parameter allows the cart to use rule promotions. You can enable this setting together with `custom_discounts_enabled`, for example, while transitioning between promotion systems. However, an individual cart can only contain one type of discount at a time.","type":"boolean","examples":[false]}}},"inventory_settings":{"title":"InventorySettings","type":"object","properties":{"defer_inventory_check":{"description":"This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout","type":"boolean","examples":[false]}}},"item_settings":{"title":"ItemSettings","type":"object","properties":{"separate_items_by_location":{"description":"When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.","type":"boolean","examples":[false]}}},"payment_intent_id":{"description":"Stripe-assigned unique identifier for the linked Payment Intent","type":"string"},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}}},"snapshot_date":{"description":"The snapshot date for the cart.","type":"string","format":"date-time"},"links":{"type":"object","properties":{"self":{"description":"A link to that specific resource.","type":"string"}},"examples":["https://useast.api.elasticpath.com/v2/carts/1"]},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"},"expires_at":{"description":"The date this expires.","type":"string"}},"title":"CartTimestamps"},"promotion_suggestions":{"description":"Array of promotion suggestions","type":"array","items":{"type":"object","properties":{"bundle":{"description":"Bundle configuration with promotion targets","type":"array","items":{"type":"object","properties":{"auto_add_free_gift":{"description":"Whether to automatically add free gift","type":"boolean"},"cart_item_id":{"description":"Cart item ID for the target","type":"string"},"quantity":{"description":"Quantity for the promotion","type":"integer"},"targets":{"description":"Array of target SKUs","type":"array","items":{"type":"string"}}},"additionalProperties":true}},"code":{"type":"string"},"info":{"type":"string"},"message":{"type":"string"},"promotion_id":{"type":"string"}}}}}},"relationships":{"type":"object","properties":{"customers":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"items":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}]}},"required":["data"]}]},"accounts":{"anyOf":[{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},{"type":"object","maxProperties":0}]},"custom_discounts":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}},"promotions":{"title":"RelationshipArray","description":"Array of relationships","type":"object","properties":{"data":{"description":"Individual relationships","type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}}}}},{"type":"object","properties":{"type":{"description":"The type of object being returned.","type":"string","const":"cart"}}}]},"included":{"type":"object","description":"Related objects that are included in the response.","properties":{"custom_discounts":{"type":"array","items":{"title":"CustomDiscountResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"discount_engine":{"description":"Specifies from where the custom discount is applied.\n","type":"string","examples":["Custom Discount Engine"]},"amount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}},"description":"The amount of the custom discount."},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The cart item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"promotions":{"type":"array","items":{"title":"CondensedPromotionResponse","type":"object","properties":{"type":{"description":"Specifies the type of the resource. Always `promotion`.","type":"string","const":"promotion","examples":["promotion"]},"id":{"description":"Specifies the UUID of the promotion.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"name":{"description":"The name of the promotion.","type":"string","examples":["Summer Sale"]},"description":{"description":"The description of the promotion.","type":"string","examples":["Get 20% off all summer items"]},"automatic":{"description":"Whether the promotion is applied automatically.","type":"boolean","examples":[true]},"promotion_type":{"description":"The type of promotion (for v1 promotions).","type":"string","examples":["discount"]},"promotion_source":{"description":"The source of the promotion (for rule promotions).","type":"string","examples":["rule-promotion"]},"start":{"description":"The start date and time of the promotion.","type":"string","format":"date-time","examples":["2024-06-01T00:00:00Z"]},"end":{"description":"The end date and time of the promotion.","type":"string","format":"date-time","examples":["2024-08-31T23:59:59Z"]}}}}}},"meta":{"type":"object","description":"Additional metadata for the cart response.","properties":{"payment_intent":{"type":"object","description":"Payment intent details with nested structure including status and other Stripe payment intent fields","additionalProperties":true}}},"errors":{"type":"array","description":"Array of error objects, if any errors occurred.","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"CartEntityResponse"}}}}}}
>
  
</StatusCodes>

---

## Update Custom Discount For Cart Item

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Custom Discount For Cart Item"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/custom-discounts/{customdiscountID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to update a custom discount in your cart item.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"Specifies the ID for the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"Specifies the ID for the cart item.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"customdiscountID","in":"path","description":"Specifies the ID for the custom discount to be updated.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"CartsCustomDiscountsResponse","properties":{"amount":{"type":"object","properties":{"amount":{"description":"Specifies an amount to be applied for the custom discount. It must be less than zero.","type":"number","examples":[-1000]},"currency":{"description":"The currency set for the custom discount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted value for the custom discount.","type":"string","examples":["-$10.00"]}}},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"title":"CartsCustomDiscountsEntityRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"title":"CartsCustomDiscountsEntityResponse"}}}}}}
>
  
</StatusCodes>

---

## Update Custom Discount For Cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Custom Discount For Cart"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartID}/custom-discounts/{customdiscountID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to update a custom discount in your cart.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"Specifies the unique ID for the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"customdiscountID","in":"path","description":"Specifies the ID for the custom discount to be updated.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"CartsCustomDiscountsResponse","properties":{"amount":{"type":"object","properties":{"amount":{"description":"Specifies an amount to be applied for the custom discount. It must be less than zero.","type":"number","examples":[-1000]},"currency":{"description":"The currency set for the custom discount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted value for the custom discount.","type":"string","examples":["-$10.00"]}}},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid","readOnly":true,"examples":["662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"]},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"title":"CartsCustomDiscountsEntityRequest"}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"CartsCustomDiscountsObject","type":"object","required":["amount","description","discount_code","discount_engine","external_id","type"],"properties":{"amount":{"type":"object","oneOf":[{"type":"number","examples":[-1000]},{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$10.00"]}}}]},"description":{"description":"Specifies a description for the custom discount.","type":"string","examples":["Custom discount description"]},"discount_code":{"description":"Specifies the discount code used for the custom discount.","type":"string","examples":["cart-custom-promo-code"]},"discount_engine":{"description":"Specifies from where the custom discount is applied. For example, Talon.one.","type":"string","examples":["Custom Discount Engine"]},"external_id":{"description":"Specifies an external id for the custom discount.","type":"string","examples":["custom-discount-external-id"]},"type":{"description":"Specifies the type of the resource. Always `custom_discount`.","type":"string","const":"custom_discount"},"id":{"description":"Specifies the UUID of the custom discount.","type":"string","format":"uuid"},"relationships":{"description":"Relationships to other resources like cart items","type":"object","properties":{"item":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The item ID this discount is related to"},"type":{"type":"string","enum":["cart_item","custom_item"]}}}}}}}}}},"title":"CartsCustomDiscountsEntityResponse"}}}}}}
>
  
</StatusCodes>

---

## Update a shipping group for a cart

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a shipping group for a cart"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartId}/shipping-groups/{shippingGroupId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a specific shipping group for a cart

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartId","in":"path","required":true,"description":"The ID of the cart","schema":{"type":"string"}},{"name":"shippingGroupId","in":"path","required":true,"description":"The ID of the shipping group","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters.","type":"string","maxLength":64},"shipping_price":{"type":"object","properties":{"total":{"type":"number"},"base":{"type":"number"},"tax":{"type":"number"},"fees":{"type":"number"},"discount":{"type":"number"}},"title":"ShippingPriceRequest"},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"includes_tax":{"type":"boolean"},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"}}}},"title":"UpdateCartShippingGroupRequest"},"example":{"data":{"type":"shipping_group","shipping_type":"express","tracking_reference":"TRACK456","shipping_price":{"base":1500,"tax":300,"fees":200},"address":{"first_name":"John","last_name":"Doe","phone_number":"(555) 555-1234","company_name":"ACME Corp","line_1":"123 Main St","line_2":"Suite 100","city":"Portland","postcode":"97201","county":"Multnomah","country":"US","region":"Oregon","instructions":"Leave at front door"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Shipping group updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Shipping Group Response","type":"object","properties":{"type":{"type":"string","const":"shipping_group"},"id":{"type":"string"},"relation":{"type":"string"},"cart_id":{"type":"string"},"order_id":{"type":"string"},"shipping_type":{"type":"string"},"tracking_reference":{"type":"string"},"external_ref":{"description":"An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.","type":"string","maxLength":64,"examples":["SG-12345"]},"address":{"title":"ShippingAddress","description":"Shipping address information. You must specify at least one of region (state/province) or county.\n","allOf":[{"anyOf":[{"title":"Address with Region","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["region"],"properties":{"region":{"description":"State, province, or region of the address.","type":"string"}}}]},{"title":"Address with County","allOf":[{"type":"object","required":["first_name","last_name","line_1","postcode","country"],"properties":{"first_name":{"description":"First name of the recipient.","type":"string","examples":["John"]},"last_name":{"description":"Last name of the recipient.","type":"string","examples":["Doe"]},"company_name":{"description":"Company of the recipient.","type":"string","examples":["John Doe Enterprises"]},"line_1":{"description":"First line of the address.","type":"string","examples":["1 Sunny Street"]},"line_2":{"description":"Second line of the address.","type":"string","examples":["Apartment 123"]},"line_3":{"description":"Third line of the address.","type":"string","maxLength":255,"examples":["Building C"]},"city":{"description":"City of the address.","type":"string","examples":["Los Angeles"]},"postcode":{"description":"Post code of the address.","type":"string","examples":["92802"]},"county":{"description":"County of the address.","type":"string","examples":["Orange"]},"country":{"description":"Country of the address.","type":"string","examples":["US"]},"region":{"description":"State, province, or region of the address.","type":"string","examples":["CA"]}},"title":"AddressCommon"},{"type":"object","required":["county"],"properties":{"county":{"description":"County of the address.","type":"string"}}}]}]},{"type":"object","properties":{"phone_number":{"description":"Phone number of the shipping recipient.","type":"string"},"instructions":{"description":"Delivery instructions.","type":"string"}}}],"examples":[{"first_name":"John","last_name":"Doe","line_1":"1 Sunny Street","line_2":"Apartment 123","line_3":"Building C","city":"Los Angeles","postcode":"92802","region":"CA","country":"US","instructions":"Please leave on porch"},{"first_name":"Jane","last_name":"Smith","line_1":"123 Main Street","city":"London","postcode":"SW1A 1AA","county":"Greater London","country":"GB","phone_number":"+44 20 7946 0958"}]},"delivery_estimate":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"title":"DeliveryEstimate"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"relationships":{"type":"object","properties":{"cart":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}},"order":{"title":"SingleRelationship","description":"Single relationship","type":"object","properties":{"data":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}}}},"discounts":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in minor currency units (e.g., cents)."},"currency":{"type":"string","description":"ISO 4217 currency code (e.g., \"USD\")."},"includes_tax":{"type":"boolean","description":"Whether the amount includes tax."}},"required":["amount","currency","includes_tax"],"title":"Money"},"code":{"type":"string","description":"The discount code used, if applicable."},"id":{"type":"string","description":"Unique identifier for the discount."},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}},"required":["amount","id"],"title":"Discount"},"title":"Discounts"},"meta":{"type":"object","properties":{"shipping_display_price":{"type":"object","properties":{"total":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"base":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"fees":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"required":["total","base"],"title":"ShippingPriceResponse"},"total_display_price":{"description":"Order pricing information.","type":"object","properties":{"with_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"tax":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}},"balance_owing":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"paid":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"authorized":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"without_discount":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping":{"title":"NonNegativeFormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total. Must be non-negative.","type":"number","minimum":0,"examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"shipping_discount":{"title":"DiscountFormattedPriceData","type":"object","properties":{"amount":{"description":"The discount amount. Must be non-positive (zero or negative).","type":"number","maximum":0,"examples":[-1000,0]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["-$10.00","$0.00"]}}}},"required":["with_tax","without_tax","tax","discount","balance_owing","paid","authorized","without_discount","shipping","shipping_discount"],"title":"OrderPriceWrapperMeta"}},"title":"ShippingGroupMeta"}}},"included":{"type":"object","description":"Related objects that are included in the response when using the include query parameter.","properties":{"items":{"description":"Array of order items associated with this shipping group.","type":"array","items":{"title":"OrderItemResponse","type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["68bf8510-bebf-47b1-96ba-8a9930c7d928"]},"quantity":{"description":"The quantity of this item were ordered.","type":"number","examples":[1]},"product_id":{"description":"The unique identifier for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["4e9c6098-9701-4839-a69c-54d8256d9012"]},"subscription_offering_id":{"description":"The unique identifier for the subscription offering for this order item.","type":"string","format":"uuid","readOnly":true,"examples":["69a39623-e681-415e-83c0-e1281010c77d"]},"name":{"description":"The name of this order item.","type":"string","examples":["Product 123"]},"sku":{"description":"The SKU code for the order item.","type":"string","examples":["IFD-1"]},"location":{"description":"The stock location for this order item.","type":"string","readOnly":true},"unit_price":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"value":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"discounts":{"type":"array","items":{"title":"DiscountData","type":"object","properties":{"amount":{"title":"OrderPriceData","type":"object","properties":{"amount":{"description":"The amount for this item.","type":"number","examples":[10000]},"currency":{"description":"The currency this item.","type":"string","examples":["USD"]},"includes_tax":{"description":"Whether this price is tax inclusive.","type":"boolean","examples":[false]}}},"code":{"type":"string"},"id":{"type":"string","format":"uuid","readOnly":true},"promotion_source":{"type":"string","description":"The source or origin of the promotion, if applicable."},"is_cart_discount":{"type":"boolean","description":"Indicates whether the discount applies to the entire cart."},"ordinal":{"type":"integer","description":"Order in which the discount was applied."},"promotion_action_id":{"type":"string","description":"Identifies the specific action within a multi-action rule promotion that produced this discount."}}}},"links":{"type":"object"},"meta":{"type":"object","properties":{"display_price":{"type":"object","properties":{"with_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"tax":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"without_discount":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}}},"discounts":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","examples":[-1000]},"currency":{"type":"string","examples":["USD"]},"formatted":{"type":"string","examples":["-$1.00"]},"constituents":{"type":"object","description":"Detailed breakdown of discount constituents by ID","additionalProperties":{"type":"object","properties":{"amount":{"type":"number","description":"The discount amount"},"currency":{"type":"string","description":"The currency code"},"formatted":{"type":"string","description":"The formatted discount amount"}}}}}}},"original_price":{"title":"OrderItemFormattedUnitPriceData","type":"object","properties":{"unit":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}},"value":{"title":"FormattedPriceData","type":"object","properties":{"amount":{"description":"The raw total.","type":"number","examples":[10000]},"currency":{"description":"The currency set for this amount.","type":"string","examples":["USD"]},"formatted":{"description":"The formatted total based on the amount and currency.","type":"string","examples":["$10.00"]}}}},"description":"The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product)."}}},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date this was created.","type":"string"},"updated_at":{"description":"The date this was last updated.","type":"string"}},"title":"Timestamps"}}},"relationships":{"type":"object","properties":{"cart_item":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"description":"The type represents the object being returned.","type":"string","examples":["order_item"]},"id":{"description":"The unique identifier for this item.","type":"string","format":"uuid","readOnly":true,"examples":["5601a4b1-9d13-42d3-8fb7-03b35169d1b6"]}}}}},"taxes":{"description":"Related tax items.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}},"promotions":{"description":"Related promotions.","type":"object","properties":{"data":{"oneOf":[{"type":"null"},{"type":"array","items":{"title":"RelationshipItem","description":"Relationship data entry","required":["type","id"],"type":"object","properties":{"type":{"description":"The type of related resource.","type":"string"},"id":{"description":"The ID of the related resource.","type":"string","format":"uuid"}}}}]}}}}},"catalog_id":{"description":"The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.","type":"string","examples":["default"]},"catalog_source":{"description":"The catalog source. Always `pim` or `legacy`.","type":"string","examples":["pim","legacy"]},"bundle_configuration":{"description":"Configuration for bundle products.","type":"object","properties":{"selected_options":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"number"}}},"component_products":{"description":"Array of component products for bundle configuration","type":"array","items":{"type":"object","properties":{"id":{"description":"Component product ID","type":"string"},"type":{"description":"Component product type","type":"string"},"attributes":{"description":"Product attributes as a generic object","type":"object","additionalProperties":true},"meta":{"description":"Product metadata as a generic object","type":"object","additionalProperties":true},"price":{"description":"Product price information as a generic object","type":"object","additionalProperties":true},"relationships":{"description":"Product relationships as a generic object","type":"object","additionalProperties":true}}}}}},"components":{"description":"Components of the bundle product.","type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"type":{"type":"string"}}}}}}},"custom_inputs":{"description":"Custom inputs for the order item as a generic object","type":"object","additionalProperties":true},"custom_attributes":{"title":"CustomAttributes","type":"object","description":"Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n  \"is_member\": {\n    \"type\": \"boolean\",\n    \"value\": true\n  },\n  \"membership_level\": {\n    \"type\": \"string\",\n    \"value\": \"premium\"\n  }\n}\n```\n","additionalProperties":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"The type of the custom attribute value.","enum":["string","integer","boolean","float"]},"value":{"description":"The value of the custom attribute.","type":["string","boolean","number"]}}},"readOnly":true},"shipping_group_id":{"description":"The shipping group ID for the order item","type":"string"},"promotion_source":{"description":"The promotion source for the order item","type":"string"},"promotion_action_id":{"description":"The action ID within the rule promotion that produced this promotion item.","type":"string","readOnly":true},"subscription_configuration":{"description":"Subscription configuration for the order item","type":"object","properties":{"plan":{"description":"Subscription plan details","type":"string"},"pricing_option":{"description":"Pricing option for the subscription","type":"string"}}}}}}},"additionalProperties":false},"errors":{"type":"array","description":"Array of validation or processing errors","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"ShippingGroupEntityResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"examples":{"currency_mismatch":{"value":{"errors":[{"status":400,"title":"Cart Currency Mismatch","detail":"The existing shipping group uses USD, cannot update shipping group with currency EUR"}]}},"invalid_dates":{"value":{"errors":[{"status":404,"title":"Date Logic Discrepancy","detail":"The start date cannot occur after the end date"}]}}}}}},"404":{"description":"Shipping group or cart not found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":["string","integer"],"description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]},"source":{"type":"string","description":"The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."},"meta":{"type":"object","description":"Additional metadata associated with the error. May include arbitrary keys.","properties":{"id":{"type":"string","description":"The resource id associated with the error"},"ids":{"type":"array","items":{"type":"string","description":"The resource ids associated with the error"}},"item_ids":{"type":"array","items":{"type":"string","description":"The cart_item ids associated with the error"}},"shipping_group_id":{"type":"string","description":"The shipping group id associated with the error"},"shipping_group_ids":{"type":"array","items":{"type":"string","description":"The shipping group ids associated with the error"}},"cart_id":{"type":"string","description":"The cart id associated with the error"},"code":{"type":"string","description":"The code associated with the error."},"order_id":{"type":"string","description":"The order id associated with the error."},"sku":{"type":"string","description":"The SKU associated with the error."},"email":{"type":"string","format":"email","description":"The email address associated with the error."},"component_product_id":{"type":"string","format":"uuid","description":"The component product ID associated with the error."},"error-meta-key":{"type":"string","description":"Custom error metadata key used for additional error context (e.g., in payment rejections)."},"value":{"description":"The value associated with the error.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"object","additionalProperties":true},{"type":"array"}]}}}},"title":"Response.ErrorItem"}}},"title":"Response.ErrorResponse"},"example":{"errors":[{"status":404,"title":"Cart shipping group not found","detail":"Cart shipping group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for cart [abc123]"}]}}}}}}
>
  
</StatusCodes>

---

## Update Tax Item on Bundle Component

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Tax Item on Bundle Component"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/carts/{cartID}/items/{cartitemID}/components/{productID}/taxes/{taxitemID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to update a tax item on a specific bundle component (component product) within a cart item. To change tax value from `rate` to `amount`, set `rate` to `null`, then set `amount` value and vice versa.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"cartID","in":"path","description":"The unique identifier of the cart.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"cartitemID","in":"path","description":"The unique identifier of the cart item.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"productID","in":"path","description":"The unique identifier of the component product within the bundle.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"taxitemID","in":"path","description":"The unique identifier of the tax item on the component product.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"updateRateTaxItemComponent":{"summary":"Update a bundle component tax item using rate","value":{"data":{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.18}}},"updateAmountTaxItemComponent":{"summary":"Update a bundle component tax item using amount","value":{"data":{"type":"tax_item","code":"GST","jurisdiction":"AU","name":"Goods and Services Tax","amount":1200}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","title":"Carts Items Taxes Object","description":"A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both.\n","oneOf":[{"title":"Tax Object (With Rate)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["rate"],"properties":{"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation.\n","type":"number","examples":[0.2]},"amount":{"description":"The tax as an absolute amount. Not allowed when rate is specified.\n","type":"number","examples":[1000]}},"not":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"}}}}]},{"title":"Tax Object (With Amount)","allOf":[{"type":"object","required":["type"],"properties":{"code":{"description":"A unique tax code in this jurisdiction.","type":"string"},"jurisdiction":{"description":"The relevant tax jurisdiction.","type":"string"},"name":{"description":"The name of the tax item.","type":"string"},"rate":{"description":"The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both.\n","type":"number"},"type":{"description":"The type of object being returned. Use `tax_item`.","type":"string","const":"tax_item"},"id":{"description":"The unique identifier for this tax item.","type":"string","format":"uuid","readOnly":true}},"title":"CartsItemsTaxesCommon"},{"type":"object","required":["amount"],"properties":{"amount":{"description":"The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation.\n","type":"number","examples":[1000]},"rate":{"description":"The tax rate as a decimal. Not allowed when amount is specified.\n","type":"number","examples":[0.2]}},"not":{"type":"object","required":["rate"],"properties":{"rate":{"type":"number"}}}}]}],"examples":[{"type":"tax_item","code":"VAT","jurisdiction":"UK","name":"Value Added Tax","rate":0.2},{"type":"tax_item","code":"EXCISE","jurisdiction":"US","name":"Excise Tax","amount":500}]}},"required":["data"],"title":"CartItemTaxesEntityResponse"},"examples":{"componentUpdatedAmountTaxItem":{"summary":"Updated bundle component tax item (amount)","value":{"data":{"id":"7aa2ddad-2c5b-4d9b-9ce9-3e8cff778a10","type":"tax_item","code":"GST","jurisdiction":"AU","name":"Goods and Services Tax","amount":1200}}}}}}}}}
>
  
</StatusCodes>

---

## Commerce Extensions Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/commerce-extensions/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Commerce Extensions Introduction"}
>
</Heading>

Commerce Extensions is a Database as a Service (DBaaS) that allows for the creation of Custom APIs and extend the capabilities of Commerce. With Custom APIs, you can efficiently manage large data sets while benefiting from both simple and complex multidimensional filtering options. Combining Custom APIs with [Composer](/docs/composer/index) enables you to deploy custom behaviors and integrations, allowing you to implement capabilities unique to your business without having to build and host that functionality from scratch.

Commerce Extensions is the next generation of Flows. Flows are not going anywhere, but going forward as we add new features, Commerce Extensions will eventually provide all the capabilities and more that Flows does. We recommend using Custom APIs for any of your new use cases.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Create a Custom API Entry

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Custom API Entry"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/entries"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a Custom API Entry

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type"],"additionalProperties":true,"properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use the `api_type` of the [Custom API](/docs/api/commerce-extensions/create-a-custom-api) for Custom API Entry.\n","examples":["wishlist_ext"]}}}}},"examples":{"Create Example":{"summary":"Create a Wishlist","value":{"data":{"type":"wishlist_ext","name":"My Wishlist","items_count":0,"keep_purchased":false,"tags":["birthday","gifts"]}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"A Custom API Entry","headers":{"ETag":{"description":"A unique identifier representing the current version of the resource. When the resource changes, the ETag value will also change. The ETag hash will be the same value as `etag_id`, and is marked as a weak entity tag string. For example: etag: W/\"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\", etag_id: 5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Entry.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use the `api_type` of the [Custom API](/docs/api/commerce-extensions/create-a-custom-api) for Custom API Entry.\n","examples":["wishlist_ext"]},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Entry.","example":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"allOf":[{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},{"type":"object","properties":{"data_size":{"type":"integer","description":"The approximate size of the data, used to enforce size limits as this value must not exceed 64 KiB. The exact calculation is intentionally unspecified to allow storage optimizations. This value will always be less than or equal to the size of the JSON representation of all field values.\n","default":0,"example":6},"resource_version":{"type":"integer","description":"A unique identifier representing the current version of the resource. When the resource changes, the `resource_version` value will also change.\n","default":0,"example":4},"etag_id":{"type":"string","description":"A unique identifier representing the current version of the resource that is a hashed string. When the resource changes, the `etag_id` will also change.\n","example":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"}}}]}},"title":"CustomAPIEntry"}}},"examples":{"Custom API Entry":{"summary":"Default Wishlist","value":{"data":{"id":"7e067539-6f6c-46e1-8c55-940031b36c6a","type":"wishlist_ext","name":"My Wishlist","items_count":0,"keep_purchased":false,"tags":["birthday","gifts"],"links":{"self":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"},"resource_version\"":0,"data_size\"":6,"etag_id\"":"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"403":{"description":"Forbidden. You do not have permission to access this resource.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Forbidden Access":{"summary":"Forbidden error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Forbidden\",\n      \"status\": \"403\",\n      \"detail\": \"You do not have permission to access this resource.\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Duplicate Custom API":{"summary":"Duplicate Custom API","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_api with the given api_type already exists\"\n    }\n  ]\n}\n"},"Duplicate Custom Field":{"summary":"Duplicate Custom Field","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_field with the given slug already exists\"\n    }\n  ]\n}\n"}}}}},"413":{"description":"Payload Too Large. The total size of a Custom API Entry must not exceed 64KB.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Payload Too Large":{"summary":"Requested entity too large","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Request Entity Too Large\",\n      \"status\": \"413\",\n      \"detail\": \"Maximum entry size reached.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}},"503":{"description":"The service is temporarily unavailable. This request can be safely retried.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Service Unavailable":{"summary":"Service Unavailable","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"An unknown error occurred\",\n      \"status\": \"503\",\n      \"title\": \"Service Unavailable\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Create a Custom API

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Custom API"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/settings/extensions/custom-apis"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a Custom API

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","name","slug","api_type"],"properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api` for Custom APIs.","const":"custom_api"},"name":{"type":"string","description":"Specifies the name of this Custom API.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom API.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.\n","pattern":"^[a-z0-9_-]{1,63}$"},"api_type":{"type":"string","description":"Specifies a unique API type for this Custom API. Entries for this API will use this value for their `type` field. This field must be suffixed with `_ext` to distinguish it from built in APIs.\n","pattern":"^[a-z0-9_]{1,59}_ext$"},"allow_upserts":{"type":"boolean","description":"Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn't exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.\n","default":false},"presentation":{"type":"object","description":"Optional presentation options for the Custom API.","properties":{"page":{"type":["string","null"],"description":"The page where this Custom API should be presented. The available values depend on the deployment and may change."},"section":{"type":["string","null"],"description":"The section within the page. Can only be set when `page` is also set.","maxLength":64}}},"relationships":{"type":"object","properties":{"parent_apis":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API. When the `type` of an object is set to `api_location` then `id` must be `/v2/extensions`.\nWhen the `type` of an object is set to `custom_api`, then `id` must be that of a Custom API that results in a relationship that does not have a depth exceeding 2 and does not result in a cycle.\n","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of parent relationship, can be `custom_api` or `api_location`.","enum":["custom_api","api_location"]}}}}}}},"title":"CustomAPIRelationships"}}}}},"examples":{"Create Example":{"summary":"Create a Custom API","value":{"data":{"type":"custom_api","name":"Wishlists","description":"Specifies the description for this Custom API.","slug":"wishlists","api_type":"wishlist_ext","relationships":{"parent_apis":{"data":[{"id":"652e39d8-d613-493e-8c20-fef99ad6327a","type":"custom_api"}]}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"A Custom API","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom API.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api` for Custom APIs.","const":"custom_api"},"name":{"type":"string","description":"Specifies the name of this Custom API.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom API.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.\n","pattern":"^[a-z0-9_-]{1,63}$"},"api_type":{"type":"string","description":"Specifies a unique API type for this Custom API. Entries for this API will use this value for their `type` field. This field must be suffixed with `_ext` to distinguish it from built in APIs.\n","pattern":"^[a-z0-9_]{1,59}_ext$"},"allow_upserts":{"type":"boolean","description":"Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn't exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.\n","default":false},"presentation":{"type":"object","description":"Optional presentation options for the Custom API.","properties":{"page":{"type":["string","null"],"description":"The page where this Custom API should be presented. The available values depend on the deployment and may change."},"section":{"type":["string","null"],"description":"The section within the page. Can only be set when `page` is also set."}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},"relationships":{"type":"object","properties":{"parent_apis":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API. When the `type` of an object is set to `api_location` then `id` must be `/v2/extensions`.\nWhen the `type` of an object is set to `custom_api`, then `id` must be that of a Custom API that results in a relationship that does not have a depth exceeding 2 and does not result in a cycle.\n","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of parent relationship, can be `custom_api` or `api_location`.","enum":["custom_api","api_location"]}}}}}}},"title":"CustomAPIRelationships"}},"title":"CustomAPI"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Duplicate Custom API":{"summary":"Duplicate Custom API","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_api with the given api_type already exists\"\n    }\n  ]\n}\n"},"Duplicate Custom Field":{"summary":"Duplicate Custom Field","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_field with the given slug already exists\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Create a Custom Field

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Custom Field"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a Custom Field

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","name","slug","field_type"],"oneOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCreateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCreateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCreateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCreateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCreateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCreateCustomField"}],"discriminator":{"propertyName":"field_type","mapping":{"boolean":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCreateCustomField"},"float":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCreateCustomField"},"integer":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCreateCustomField"},"string":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCreateCustomField"},"any":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCreateCustomField"},"list":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseCreateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCreateCustomField"}}}}}},"examples":{"Create Boolean Field":{"summary":"Create a Boolean Field","value":{"data":{"type":"custom_field","name":"Keep Purchased Items","description":"This field stores whether or not to keep purchased items on the wishlist.","slug":"keep_purchased","field_type":"boolean","validation":{"boolean":{"allow_null_values":true,"immutable":false}}}}},"Create Float Field":{"summary":"Create a Float Field","value":{"data":{"type":"custom_field","name":"Items Weight","description":"This field stores the total weight (in kilograms) of the items in the wishlist.","slug":"items_weight","field_type":"float","validation":{"float":{"min_value":0,"max_value":null,"allow_null_values":true,"immutable":false}}}}},"Create Integer Field":{"summary":"Create a Integer Field","value":{"data":{"type":"custom_field","name":"Items Count","description":"This field stores the total count of items in the wishlist.","slug":"items_count","field_type":"integer","validation":{"integer":{"min_value":0,"max_value":null,"allow_null_values":true,"immutable":false}}}}},"Create String Field":{"summary":"Create a String Field","value":{"data":{"type":"custom_field","name":"Name","description":"This field stores the name of the wishlist.","slug":"name","field_type":"string","validation":{"string":{"min_length":3,"max_length":128,"regex":null,"allow_null_values":true,"immutable":false,"unique":"no","unique_case_insensitivity":false}}}}},"Create Any Field":{"summary":"Create an Any Field","value":{"data":{"type":"custom_field","name":"Metadata","description":"This field stores arbitrary metadata as a JSON object.","slug":"metadata","field_type":"any","validation":{"any":{"allow_null_values":true,"immutable":false}}}}},"Create List Field":{"summary":"Create a List Field","value":{"data":{"type":"custom_field","name":"Tags","description":"This field stores a list of tags for the wishlist.","slug":"tags","field_type":"list","validation":{"list":{"allow_null_values":true,"immutable":false,"min_length":0,"max_length":100,"allowed_type":"string"}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"A Custom Field","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCustomField"},{"description":"The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. This provides maximum flexibility for storing complex or varying data structures.\n\n**Important:** When updating an entry, the `any` field value is completely replaced, not merged. For example, if a field contains `{\"a\": 1, \"b\": 2}` and you update it with `{\"a\": 99}`, the result will be `{\"a\": 99}` (not `{\"a\": 99, \"b\": 2}`). Standard partial update behavior still applies at the entry level: if you omit the field entirely from an update request, the existing value is preserved.\n\n**Note:** Filtering is not supported on `any` fields.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCustomField"},{"description":"The `list` field type allows storing an array of primitive values (strings, integers, booleans, floats, or null). The list can contain up to 1000 elements.\n\n### Filtering\n\nList fields support the following filter operators:\n\n**List Content Operators** (operate on the entire list):\n- `contains(field, value)` - matches entries where the list contains the specified value\n- `contains_any(field, value1, value2, ...)` - matches entries where the list contains any of the specified values\n- `contains_all(field, value1, value2, ...)` - matches entries where the list contains all of the specified values (**requires `allowed_type` to not be `any`**)\n- `is_null(field)` - matches entries where the list field is null\n\n**Index-Based Access** (access specific elements by position):\n- `eq(field[index], value)` - matches entries where the element at the specified index equals the value\n- `like(field[index], pattern)` - matches entries where the string element at the index matches the pattern\n- `in(field[index], value1, value2, ...)` - matches entries where the element at the index is one of the specified values\n- `is_null(field[index])` - matches entries where the element at the index is null\n- `lt`, `le`, `gt`, `ge(field[index], value)` - relational comparisons (**requires `allowed_type` to not be `any`**)\n\nIndex must be a non-negative integer from 0 to 999. Negative indices are not supported.\n\n**Length Access** (filter by array length):\n- `eq(field.length, value)` - matches entries where the list has exactly the specified length\n- `lt(field.length, value)`, `le(field.length, value)` - matches entries where the list length is less than (or equal to) the value\n- `gt(field.length, value)`, `ge(field.length, value)` - matches entries where the list length is greater than (or equal to) the value\n- `in(field.length, value1, value2, ...)` - matches entries where the list length is one of the specified values\n\n### Typed Lists vs Untyped Lists\n\nWhen `allowed_type` is set to a specific type (e.g., `\"string\"`, `\"integer\"`), additional operators become available:\n- `contains_all` - efficiently matches all specified values using exact type comparison\n- Relational operators (`lt`, `le`, `gt`, `ge`) on index access - compare values with proper type handling\n\nWhen `allowed_type` is `\"any\"` (the default), these operators are not available because type coercion would make comparisons unreliable.\n\n### Type Coercion (Untyped Lists)\n\nFor lists with `allowed_type: \"any\"`, filter operators use type coercion to match values:\n- `contains(field, 1)` matches both integer `1` and string `\"1\"`\n- `contains(field, true)` matches both boolean `true` and string `\"true\"`\n- `eq(field[0], 1)` matches both integer `1` and string `\"1\"` at index 0\n\n### Type Mismatch Behavior (Typed Lists)\n\nFor operators that require exact type matching (`contains_all`, `in` on typed fields), filtering with a value that cannot be converted to the `allowed_type` returns a 400 error. For example, `contains_all(field, \"foo\")` on an integer list returns an error because `\"foo\"` cannot be converted to an integer.\n\nFor operators that use type coercion (`contains`, `contains_any`), filtering with a non-matching type returns zero results. For example, `contains(field, \"foo\")` on an integer list returns no matches because the string `\"foo\"` doesn't match any integers in the list.\n\n**Note:** Float elements in lists are not reliably filterable with `eq()` due to floating-point precision issues.\n\n**Note:** If a field slug matches the index access pattern (e.g., `myfield[0]`) or length access pattern (e.g., `myfield.length`), filtering on that field may not work as expected. To avoid conflicts, use only lowercase letters, numbers, underscores, and hyphens in field slugs.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCustomField"}],"discriminator":{"propertyName":"field_type","mapping":{"boolean":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCustomField"},"float":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCustomField"},"integer":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCustomField"},"string":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCustomField"},"any":{"description":"The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. This provides maximum flexibility for storing complex or varying data structures.\n\n**Important:** When updating an entry, the `any` field value is completely replaced, not merged. For example, if a field contains `{\"a\": 1, \"b\": 2}` and you update it with `{\"a\": 99}`, the result will be `{\"a\": 99}` (not `{\"a\": 99, \"b\": 2}`). Standard partial update behavior still applies at the entry level: if you omit the field entirely from an update request, the existing value is preserved.\n\n**Note:** Filtering is not supported on `any` fields.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCustomField"},"list":{"description":"The `list` field type allows storing an array of primitive values (strings, integers, booleans, floats, or null). The list can contain up to 1000 elements.\n\n### Filtering\n\nList fields support the following filter operators:\n\n**List Content Operators** (operate on the entire list):\n- `contains(field, value)` - matches entries where the list contains the specified value\n- `contains_any(field, value1, value2, ...)` - matches entries where the list contains any of the specified values\n- `contains_all(field, value1, value2, ...)` - matches entries where the list contains all of the specified values (**requires `allowed_type` to not be `any`**)\n- `is_null(field)` - matches entries where the list field is null\n\n**Index-Based Access** (access specific elements by position):\n- `eq(field[index], value)` - matches entries where the element at the specified index equals the value\n- `like(field[index], pattern)` - matches entries where the string element at the index matches the pattern\n- `in(field[index], value1, value2, ...)` - matches entries where the element at the index is one of the specified values\n- `is_null(field[index])` - matches entries where the element at the index is null\n- `lt`, `le`, `gt`, `ge(field[index], value)` - relational comparisons (**requires `allowed_type` to not be `any`**)\n\nIndex must be a non-negative integer from 0 to 999. Negative indices are not supported.\n\n**Length Access** (filter by array length):\n- `eq(field.length, value)` - matches entries where the list has exactly the specified length\n- `lt(field.length, value)`, `le(field.length, value)` - matches entries where the list length is less than (or equal to) the value\n- `gt(field.length, value)`, `ge(field.length, value)` - matches entries where the list length is greater than (or equal to) the value\n- `in(field.length, value1, value2, ...)` - matches entries where the list length is one of the specified values\n\n### Typed Lists vs Untyped Lists\n\nWhen `allowed_type` is set to a specific type (e.g., `\"string\"`, `\"integer\"`), additional operators become available:\n- `contains_all` - efficiently matches all specified values using exact type comparison\n- Relational operators (`lt`, `le`, `gt`, `ge`) on index access - compare values with proper type handling\n\nWhen `allowed_type` is `\"any\"` (the default), these operators are not available because type coercion would make comparisons unreliable.\n\n### Type Coercion (Untyped Lists)\n\nFor lists with `allowed_type: \"any\"`, filter operators use type coercion to match values:\n- `contains(field, 1)` matches both integer `1` and string `\"1\"`\n- `contains(field, true)` matches both boolean `true` and string `\"true\"`\n- `eq(field[0], 1)` matches both integer `1` and string `\"1\"` at index 0\n\n### Type Mismatch Behavior (Typed Lists)\n\nFor operators that require exact type matching (`contains_all`, `in` on typed fields), filtering with a value that cannot be converted to the `allowed_type` returns a 400 error. For example, `contains_all(field, \"foo\")` on an integer list returns an error because `\"foo\"` cannot be converted to an integer.\n\nFor operators that use type coercion (`contains`, `contains_any`), filtering with a non-matching type returns zero results. For example, `contains(field, \"foo\")` on an integer list returns no matches because the string `\"foo\"` doesn't match any integers in the list.\n\n**Note:** Float elements in lists are not reliably filterable with `eq()` due to floating-point precision issues.\n\n**Note:** If a field slug matches the index access pattern (e.g., `myfield[0]`) or length access pattern (e.g., `myfield.length`), filtering on that field may not work as expected. To avoid conflicts, use only lowercase letters, numbers, underscores, and hyphens in field slugs.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCustomField"}}},"title":"CustomField"}}},"examples":{"Boolean Field":{"summary":"Boolean Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Keep Purchased Items","description":"This field stores whether or not to keep purchased items on the wishlist.","slug":"keep_purchased","field_type":"boolean","validation":{"boolean":{"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Float Field":{"summary":"Float Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Items Weight","description":"This field stores the total weight (in kilograms) of the items in the wishlist.","slug":"items_weight","field_type":"float","validation":{"float":{"min_value":0,"max_value":null,"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Integer Field":{"summary":"Integer Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Items Count","description":"This field stores the total count of items in the wishlist.","slug":"items_count","field_type":"integer","validation":{"integer":{"min_value":null,"max_value":null,"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"String Field":{"summary":"String Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Name","description":"This field stores the name of the wishlist.","slug":"name","field_type":"string","validation":{"string":{"min_length":3,"max_length":128,"regex":null,"allow_null_values":true,"immutable":false,"unique":"no","unique_case_insensitivity":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Any Field":{"summary":"Any Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Metadata","description":"This field stores arbitrary metadata as a JSON object.","slug":"metadata","field_type":"any","validation":{"any":{"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"List Field":{"summary":"List Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Tags","description":"This field stores a list of tags for the wishlist.","slug":"tags","field_type":"list","validation":{"list":{"allow_null_values":true,"immutable":false,"min_length":null,"max_length":null,"allowed_type":"string"}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Duplicate Custom API":{"summary":"Duplicate Custom API","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_api with the given api_type already exists\"\n    }\n  ]\n}\n"},"Duplicate Custom Field":{"summary":"Duplicate Custom Field","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_field with the given slug already exists\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Custom APIs

Custom APIs allow you to extend the capabilities of Commerce. With Custom APIs, you can efficiently manage large data sets while benefiting from both simple and complex multidimensional filtering options. Combining Custom APIs with [Composer](/docs/composer/index) enables you to deploy custom behaviors and integrations, allowing you to implement capabilities unique to your business without having to build and host that functionality from scratch.

A Custom API is composed of one or more [Custom Fields](/docs/api/commerce-extensions/custom-fields) and allows you to create [Entries](/docs/api/commerce-extensions/custom-api-entries). In database terms, a Custom API can be thought of as a table, with fields representing the columns of the table, and entries serving as the database records.

## Custom APIs vs Non-Core Flows

Custom APIs are the next generation of Non-Core Flows. Here is a comparison of current features of Non-Core Flows and Custom APIs. This will be updated as we release more capabilities.

| Feature                                                                                                                   | Non-Core Flows | Commerce Extensions                                            |
|---------------------------------------------------------------------------------------------------------------------------|----------------|----------------------------------------------------------------|
| Build new APIs                                                                                                            | ✅              | ✅                                                              |
| Access Level                                                                                                              | Implicit       | [Customizable](/docs/api/permissions/custom-api-role-policies) |
| [Filtering](/docs/api/commerce-extensions/list-custom-api-entries#filtering)                                              | ⛔️             | ✅                                                              |
| [Sorting](/docs/api/commerce-extensions/list-custom-api-entries#sorting)                                                  | ⛔️             | ✅                                                              |
| [Events](/docs/api/commerce-extensions/custom-api-entries#events)                                                         | ⛔️             | ✅                                                              |
| [Conditional Updates](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#conditional-updates) | ⛔️             | ✅                                                              |

The [Custom Fields Overview](/docs/api/commerce-extensions/custom-fields) lists the comparison of different types and validation available in Custom APIs vs Non-Core Flows.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Custom API Entries

A **Custom API Entry** is a specific instance of a resource, such as a single wishlist in a Custom API for wishlists.

Custom API Entries can be accessed in two different ways, via the **extension** endpoint, or the **settings** endpoint:

* Extension Endpoint: `/v2/extensions/{custom-api-slug}` - This is the primary endpoint created for use. Most clients should use this endpoint as it adheres to the semantics of the configuration. Retrieve the [OpenAPI Specifications](/docs/api/commerce-extensions/get-open-api-specification) to learn how to interact with this endpoint.
* Settings Endpoint: `/v2/settings/extensions/custom-apis/{custom-api-id}/entries/` - This endpoint should only be used in cases where you want to interact with your Custom APIs in a generic way in an admin capacity.

Currently, the distinction between these endpoints is minimal. The extension endpoint uses a slug in the URL path, and the settings endpoint uses an ID. For most use cases involving the new Custom API, we recommend using the extension endpoint.

Conceptually, the settings endpoint is analogous to reflection in most programming languages. You use it when you want to operate in a generic way. For example, we used the settings endpoint to build Commerce Manager. Another example is if you need to import and export various types of data from CSV files. Instead of writing multiple scripts for different extension endpoints, you can write one script that operates on the settings endpoint.

## Events

You can integrate Commerce Extensions with your external systems by observing the appropriate events. For more information, see [Integrations](/docs/api/integrations/integrations-introduction).

Given you have a Custom API with `api_type` of `wishlist_ext` and you want to perform additional processing when an action is taken, like when a wishlist is created:

```bash
curl -X POST https://useast.api.elasticpath.com/v2/extensions/wishlists \
  -H "Authorization: Bearer XXXX" \
  -H "Content-Type: application/json" \
  -d $ {
    "data": {
      "type": "wishlist_ext",
      "name": "My Wishlist",
      "items_count": 0,
      "keep_purchased": false
    }
  }
```

When you [create an integration](/docs/api/integrations/create-integration) with `wishlist_ext.created` in `observes` field.
Then the configured `webhook` or `aws_sqs` will receive the appropriate message.

You can configure integrations to observe the following events for your Custom API Entries:
* Created
* Updated
* Deleted

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Custom Fields

A Custom Field represents a single field of data (for example a Product Rating). A Custom API is composed of one or more Custom Fields.

Here is a comparison of different types and validation available in Custom APIs vs Non-Core Flows.

| Feature                                       | Non-Core Flows | Commerce Extensions                        |
|-----------------------------------------------|----------------|--------------------------------------------|
| Data Type: String                             | ✅              | ✅                                          |
| Data Type: Integer                            | ✅              | ✅                                          |
| Data Type: Float                              | ✅              | ✅                                          |
| Data Type: Boolean                            | ✅              | ✅                                          |
| Data Type: List                               | ⛔              | ✅                                          |
| Data Type: Any                                | ⛔              | ✅                                          |
| Data Type: Date & Time                        | ✅              | ✅ Replaced by Regex Validation (See Below) |
| Data Type: One To Many                        | ✅              | Planned                                    |
| Validation: Regular Expression                | ⛔️             | ✅                                          |
| Validation: Slug/Email                        | ✅              | ✅ Replaced by Regex Validation (See Below) |
| Validation: Min/Max Value                     | ✅              | ✅                                          |
| Validation: Enum(String)                      | ✅              | ✅ Replaced by Regex validation (See Below) |
| Validation: Enum(Float/Integer)               | ✅              | ⛔️                                         |
| Validation: Allow null values                 | ⛔              | ✅                                          |
| Validation: Unique(String)                    | ⛔              | ✅                                          |
| Validation: Unique Case Insensitivity(String) | ⛔              | ✅                                          |
| Validation: Immutable                         | ⛔              | ✅                                          |

## Validation

When [creating](/docs/api/commerce-extensions/create-a-custom-field#request) or [updating](/docs/api/commerce-extensions/update-a-custom-field#request) a Custom Field, `validation` can be used to limit the values that may be stored in the corresponding Custom API Entry.

:::note

All validation changes, such as those to `allow_null_values` and any type specific rules, apply to new entries only. Existing Custom API Entry records are unaffected until updated.

:::

### Integer Validation
- `min_value`: Specifies the minimum whole number that can be stored. If set, it must be less than `max_value`.
- `max_value`: Specifies the maximum whole number that can be stored. If set, it must be greater than `min_value`.

sample integer validation object:

```json
{
  "validation": {
    "integer": {
      "min_value": 0,
      "max_value": 32
    }
  }
}
```
Even if no validation is set, field_type `integer` only supports values between -2^53+1 and 2^53+1. This is because the JSON format doesn't guarantee that values outside this range are portable ([Source](https://datatracker.ietf.org/doc/html/rfc7159#section-6)).

### Float Validation
- `min_value`: Specifies the minimum number that can be stored. If set, it must be less than `max_value`.
- `max_value`: Specifies the maximum number that can be stored. If set, it must be greater than `min_value`.

sample float validation object:

```json
{
  "validation": {
    "float": {
      "min_value": 0.01,
      "max_value": 32.01
    }
  }
}
```

The `float` field_type cannot accurately represent some numbers and so using very small or large numbers might lose precision. We recommend that API clients use either the `integer` field_type if applicable , or the `string` data type if perfect precision or recall is required.

### String Validation
- `min_length`: Specifies the minimum number of characters that can be stored. If set, it must be greater than 0 and less than `max_length`.
- `max_length`: Specifies the maximum number of characters that can be stored. If set, it must be greater than 0 and `min_length`.
- `regex`: An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression used to restrict the specific characters that can be stored. It must be less than 1024 characters.
- `unique`: Specifies whether the field must have unique constraint or not. It must be `yes` or `no`.
- `unique_case_insensitivity`: Applies when `unique` is set to `yes`. It controls whether values with different cases (for example, `ABC` and `abc`) should conflict. It must be `true` or `false`.
  sample string validation object:

```json
{
  "validation": {
    "string": {
      "min_length": 0,
      "max_length": 64,
      "regex": "^.+\\.(jpg|jpeg|png|gif|pdf)$",
      "unique": "yes"
      "unique_case_insensitivity": true
    }
  }
}
```
Even if no validation is set, field_type `string` only supports values that are up to `65535` characters long.

#### Date & Time Values With Regular Expressions

While Commerce Extensions does not have a native date or time type, you can none-the-less use these values in Commerce Extensions, by using the `string` field type and `regex` validation. To ensure that
ordering is handled properly you should follow the guidance in [RFC 3339 - Section 5.1 Ordering](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.1), namely store the fields in order of least to most precise,
and in the same timezone, this will ensure that comparison operators (e.g., `gt`) and sorting, work as expected, for example the following regex will force all values to be in seconds in UTC: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$`

One thing to keep in mind is that some libraries, especially when dealing with sub-seconds might only display them if they are non-zero, and you will want to ensure that they are fully padded to the same length.

#### Enum Values with Regular Expressions

You can ensure that only some values are allowed using the regular expression `^(alpha|bravo|charlie)$`.

#### Slug Values with Regular Expressions

Slugs can be replaced with the regular expression `^[a-z][a-z0-9-]*$`, this will ensure that the field starts with a lower case letter, and then has lower case letters, numbers or hyphens. You can tweak this regular expression as needed to suit your needs.

### Email Validation with Regular Expressions

E-mails can be tricky to validate properly, especially because many services _accept_ e-mails that are not valid, and reject e-mail addresses that are technically valid. Additionally, your own capabilities and purposes might inform your decision (e.g., if you support [i18n addresses](https://datatracker.ietf.org/doc/html/rfc6530) or don't then the set of allowed e-mails changes).

### List Validation
- `min_length`: Specifies the minimum number of elements that must be in the list.
- `max_length`: Specifies the maximum number of elements allowed in the list. The maximum supported value is 1000.
- `allowed_type`: Specifies the primitive type that all elements in the list must be. Valid values are `string`, `integer`, `boolean`, `float`, or `any`. The default is `any`, which allows mixed types. This value cannot be changed after the field is created.

sample list validation object:

```json
{
  "validation": {
    "list": {
      "min_length": 1,
      "max_length": 100,
      "allowed_type": "string"
    }
  }
}
```

### Any Validation

The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. When updating an entry, the `any` field value is completely replaced, not merged. Filtering is not supported on `any` fields.

sample any validation object:

```json
{
  "validation": {
    "any": {
      "allow_null_values": true,
      "immutable": false
    }
  }
}
```

### Null Values

All Custom Fields can be configured to restrict the storage of `null` values for that field on a Custom API Entry. By default, this is `true`.

sample validation object :

```json
{
  "validation": {
    "boolean": {
      "allow_null_values": false,
      "immutable": false
    }
  }
}
```

### Immutable

When [creating](/docs/api/commerce-extensions/create-a-custom-field#request) a Custom Field, it can be configured to be `immutable`. When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests. By default, this is `false`.

sample validation object :

```json
{
  "validation": {
    "boolean": {
      "immutable": false
    }
  }
}
```

## Presentation

When [creating](/docs/api/commerce-extensions/create-a-custom-field#request) or [updating](/docs/api/commerce-extensions/update-a-custom-field#request) a Custom Field, `presentation` can be used to influence the layout and order of fields within Commerce Manager. It does not affect the order of keys within JSON, nor influence any behaviour outside of Commerce Manager.

## Reserved Slugs

The following values cannot be used as a `slug` in a Custom Field.

- slug
- type
- id
- meta
- created_at
- updated_at
- links
- relationships
- attributes
- attribute
- dimension
- dimensions
- weight
- weights

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Delete a Custom API

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Custom API"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a Custom API

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Delete a Custom API Entry

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Custom API Entry"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/entries/{custom-api-entry-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a Custom API Entry

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"If-Match","description":"When If-Match is set, the value must be W/\"{etag_id}\". If the value of the header matches, the request completes. If not, HTTP 412 Precondition Failed is returned.\n","in":"header","required":true,"schema":{"type":"string","format":"string"}},{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"custom-api-entry-id","description":"The unique identifier of the Custom API Entry.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"7e067539-6f6c-46e1-8c55-940031b36c6a"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"403":{"description":"Forbidden. You do not have permission to access this resource.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Forbidden Access":{"summary":"Forbidden error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Forbidden\",\n      \"status\": \"403\",\n      \"detail\": \"You do not have permission to access this resource.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"412":{"description":"Precondition Failed.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Precondition Failed":{"summary":"Provided ETag does not match the current ETag.","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Precondition Failed\",\n      \"status\": \"412\",\n      \"detail\": \"The provided ETag 'W/\\\"4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a\\\"', does not match the current ETag 'W/\\\"ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d\\\"'.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}},"503":{"description":"The service is temporarily unavailable. This request can be safely retried.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Service Unavailable":{"summary":"Service Unavailable","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"An unknown error occurred\",\n      \"status\": \"503\",\n      \"title\": \"Service Unavailable\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Delete a Custom Field

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Custom Field"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/fields/{custom-field-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a Custom Field

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"custom-field-id","description":"The unique identifier of the Custom Field.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"859aeba1-03c2-4822-bd4c-89afce93d7eb"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get a Custom API

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Custom API"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a Custom API

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Custom API","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom API.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api` for Custom APIs.","const":"custom_api"},"name":{"type":"string","description":"Specifies the name of this Custom API.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom API.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.\n","pattern":"^[a-z0-9_-]{1,63}$"},"api_type":{"type":"string","description":"Specifies a unique API type for this Custom API. Entries for this API will use this value for their `type` field. This field must be suffixed with `_ext` to distinguish it from built in APIs.\n","pattern":"^[a-z0-9_]{1,59}_ext$"},"allow_upserts":{"type":"boolean","description":"Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn't exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.\n","default":false},"presentation":{"type":"object","description":"Optional presentation options for the Custom API.","properties":{"page":{"type":["string","null"],"description":"The page where this Custom API should be presented. The available values depend on the deployment and may change."},"section":{"type":["string","null"],"description":"The section within the page. Can only be set when `page` is also set."}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},"relationships":{"type":"object","properties":{"parent_apis":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API. When the `type` of an object is set to `api_location` then `id` must be `/v2/extensions`.\nWhen the `type` of an object is set to `custom_api`, then `id` must be that of a Custom API that results in a relationship that does not have a depth exceeding 2 and does not result in a cycle.\n","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of parent relationship, can be `custom_api` or `api_location`.","enum":["custom_api","api_location"]}}}}}}},"title":"CustomAPIRelationships"}},"title":"CustomAPI"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get a Custom API Entry

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Custom API Entry"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/entries/{custom-api-entry-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a Custom API Entry

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"custom-api-entry-id","description":"The unique identifier of the Custom API Entry.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"7e067539-6f6c-46e1-8c55-940031b36c6a"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Custom API Entry","headers":{"ETag":{"description":"A unique identifier representing the current version of the resource. When the resource changes, the ETag value will also change. The ETag hash will be the same value as `etag_id`, and is marked as a weak entity tag string. For example: etag: W/\"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\", etag_id: 5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Entry.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use the `api_type` of the [Custom API](/docs/api/commerce-extensions/create-a-custom-api) for Custom API Entry.\n","examples":["wishlist_ext"]},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Entry.","example":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"allOf":[{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},{"type":"object","properties":{"data_size":{"type":"integer","description":"The approximate size of the data, used to enforce size limits as this value must not exceed 64 KiB. The exact calculation is intentionally unspecified to allow storage optimizations. This value will always be less than or equal to the size of the JSON representation of all field values.\n","default":0,"example":6},"resource_version":{"type":"integer","description":"A unique identifier representing the current version of the resource. When the resource changes, the `resource_version` value will also change.\n","default":0,"example":4},"etag_id":{"type":"string","description":"A unique identifier representing the current version of the resource that is a hashed string. When the resource changes, the `etag_id` will also change.\n","example":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"}}}]}},"title":"CustomAPIEntry"}}},"examples":{"Custom API Entry":{"summary":"Default Wishlist","value":{"data":{"id":"7e067539-6f6c-46e1-8c55-940031b36c6a","type":"wishlist_ext","name":"My Wishlist","items_count":0,"keep_purchased":false,"tags":["birthday","gifts"],"links":{"self":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"},"resource_version\"":0,"data_size\"":6,"etag_id\"":"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"403":{"description":"Forbidden. You do not have permission to access this resource.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Forbidden Access":{"summary":"Forbidden error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Forbidden\",\n      \"status\": \"403\",\n      \"detail\": \"You do not have permission to access this resource.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get a Custom Field

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Custom Field"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/fields/{custom-field-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a Custom Field

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"custom-field-id","description":"The unique identifier of the Custom Field.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"859aeba1-03c2-4822-bd4c-89afce93d7eb"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Custom Field","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCustomField"},{"description":"The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. This provides maximum flexibility for storing complex or varying data structures.\n\n**Important:** When updating an entry, the `any` field value is completely replaced, not merged. For example, if a field contains `{\"a\": 1, \"b\": 2}` and you update it with `{\"a\": 99}`, the result will be `{\"a\": 99}` (not `{\"a\": 99, \"b\": 2}`). Standard partial update behavior still applies at the entry level: if you omit the field entirely from an update request, the existing value is preserved.\n\n**Note:** Filtering is not supported on `any` fields.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCustomField"},{"description":"The `list` field type allows storing an array of primitive values (strings, integers, booleans, floats, or null). The list can contain up to 1000 elements.\n\n### Filtering\n\nList fields support the following filter operators:\n\n**List Content Operators** (operate on the entire list):\n- `contains(field, value)` - matches entries where the list contains the specified value\n- `contains_any(field, value1, value2, ...)` - matches entries where the list contains any of the specified values\n- `contains_all(field, value1, value2, ...)` - matches entries where the list contains all of the specified values (**requires `allowed_type` to not be `any`**)\n- `is_null(field)` - matches entries where the list field is null\n\n**Index-Based Access** (access specific elements by position):\n- `eq(field[index], value)` - matches entries where the element at the specified index equals the value\n- `like(field[index], pattern)` - matches entries where the string element at the index matches the pattern\n- `in(field[index], value1, value2, ...)` - matches entries where the element at the index is one of the specified values\n- `is_null(field[index])` - matches entries where the element at the index is null\n- `lt`, `le`, `gt`, `ge(field[index], value)` - relational comparisons (**requires `allowed_type` to not be `any`**)\n\nIndex must be a non-negative integer from 0 to 999. Negative indices are not supported.\n\n**Length Access** (filter by array length):\n- `eq(field.length, value)` - matches entries where the list has exactly the specified length\n- `lt(field.length, value)`, `le(field.length, value)` - matches entries where the list length is less than (or equal to) the value\n- `gt(field.length, value)`, `ge(field.length, value)` - matches entries where the list length is greater than (or equal to) the value\n- `in(field.length, value1, value2, ...)` - matches entries where the list length is one of the specified values\n\n### Typed Lists vs Untyped Lists\n\nWhen `allowed_type` is set to a specific type (e.g., `\"string\"`, `\"integer\"`), additional operators become available:\n- `contains_all` - efficiently matches all specified values using exact type comparison\n- Relational operators (`lt`, `le`, `gt`, `ge`) on index access - compare values with proper type handling\n\nWhen `allowed_type` is `\"any\"` (the default), these operators are not available because type coercion would make comparisons unreliable.\n\n### Type Coercion (Untyped Lists)\n\nFor lists with `allowed_type: \"any\"`, filter operators use type coercion to match values:\n- `contains(field, 1)` matches both integer `1` and string `\"1\"`\n- `contains(field, true)` matches both boolean `true` and string `\"true\"`\n- `eq(field[0], 1)` matches both integer `1` and string `\"1\"` at index 0\n\n### Type Mismatch Behavior (Typed Lists)\n\nFor operators that require exact type matching (`contains_all`, `in` on typed fields), filtering with a value that cannot be converted to the `allowed_type` returns a 400 error. For example, `contains_all(field, \"foo\")` on an integer list returns an error because `\"foo\"` cannot be converted to an integer.\n\nFor operators that use type coercion (`contains`, `contains_any`), filtering with a non-matching type returns zero results. For example, `contains(field, \"foo\")` on an integer list returns no matches because the string `\"foo\"` doesn't match any integers in the list.\n\n**Note:** Float elements in lists are not reliably filterable with `eq()` due to floating-point precision issues.\n\n**Note:** If a field slug matches the index access pattern (e.g., `myfield[0]`) or length access pattern (e.g., `myfield.length`), filtering on that field may not work as expected. To avoid conflicts, use only lowercase letters, numbers, underscores, and hyphens in field slugs.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCustomField"}],"discriminator":{"propertyName":"field_type","mapping":{"boolean":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCustomField"},"float":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCustomField"},"integer":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCustomField"},"string":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCustomField"},"any":{"description":"The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. This provides maximum flexibility for storing complex or varying data structures.\n\n**Important:** When updating an entry, the `any` field value is completely replaced, not merged. For example, if a field contains `{\"a\": 1, \"b\": 2}` and you update it with `{\"a\": 99}`, the result will be `{\"a\": 99}` (not `{\"a\": 99, \"b\": 2}`). Standard partial update behavior still applies at the entry level: if you omit the field entirely from an update request, the existing value is preserved.\n\n**Note:** Filtering is not supported on `any` fields.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCustomField"},"list":{"description":"The `list` field type allows storing an array of primitive values (strings, integers, booleans, floats, or null). The list can contain up to 1000 elements.\n\n### Filtering\n\nList fields support the following filter operators:\n\n**List Content Operators** (operate on the entire list):\n- `contains(field, value)` - matches entries where the list contains the specified value\n- `contains_any(field, value1, value2, ...)` - matches entries where the list contains any of the specified values\n- `contains_all(field, value1, value2, ...)` - matches entries where the list contains all of the specified values (**requires `allowed_type` to not be `any`**)\n- `is_null(field)` - matches entries where the list field is null\n\n**Index-Based Access** (access specific elements by position):\n- `eq(field[index], value)` - matches entries where the element at the specified index equals the value\n- `like(field[index], pattern)` - matches entries where the string element at the index matches the pattern\n- `in(field[index], value1, value2, ...)` - matches entries where the element at the index is one of the specified values\n- `is_null(field[index])` - matches entries where the element at the index is null\n- `lt`, `le`, `gt`, `ge(field[index], value)` - relational comparisons (**requires `allowed_type` to not be `any`**)\n\nIndex must be a non-negative integer from 0 to 999. Negative indices are not supported.\n\n**Length Access** (filter by array length):\n- `eq(field.length, value)` - matches entries where the list has exactly the specified length\n- `lt(field.length, value)`, `le(field.length, value)` - matches entries where the list length is less than (or equal to) the value\n- `gt(field.length, value)`, `ge(field.length, value)` - matches entries where the list length is greater than (or equal to) the value\n- `in(field.length, value1, value2, ...)` - matches entries where the list length is one of the specified values\n\n### Typed Lists vs Untyped Lists\n\nWhen `allowed_type` is set to a specific type (e.g., `\"string\"`, `\"integer\"`), additional operators become available:\n- `contains_all` - efficiently matches all specified values using exact type comparison\n- Relational operators (`lt`, `le`, `gt`, `ge`) on index access - compare values with proper type handling\n\nWhen `allowed_type` is `\"any\"` (the default), these operators are not available because type coercion would make comparisons unreliable.\n\n### Type Coercion (Untyped Lists)\n\nFor lists with `allowed_type: \"any\"`, filter operators use type coercion to match values:\n- `contains(field, 1)` matches both integer `1` and string `\"1\"`\n- `contains(field, true)` matches both boolean `true` and string `\"true\"`\n- `eq(field[0], 1)` matches both integer `1` and string `\"1\"` at index 0\n\n### Type Mismatch Behavior (Typed Lists)\n\nFor operators that require exact type matching (`contains_all`, `in` on typed fields), filtering with a value that cannot be converted to the `allowed_type` returns a 400 error. For example, `contains_all(field, \"foo\")` on an integer list returns an error because `\"foo\"` cannot be converted to an integer.\n\nFor operators that use type coercion (`contains`, `contains_any`), filtering with a non-matching type returns zero results. For example, `contains(field, \"foo\")` on an integer list returns no matches because the string `\"foo\"` doesn't match any integers in the list.\n\n**Note:** Float elements in lists are not reliably filterable with `eq()` due to floating-point precision issues.\n\n**Note:** If a field slug matches the index access pattern (e.g., `myfield[0]`) or length access pattern (e.g., `myfield.length`), filtering on that field may not work as expected. To avoid conflicts, use only lowercase letters, numbers, underscores, and hyphens in field slugs.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCustomField"}}},"title":"CustomField"}}},"examples":{"Boolean Field":{"summary":"Boolean Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Keep Purchased Items","description":"This field stores whether or not to keep purchased items on the wishlist.","slug":"keep_purchased","field_type":"boolean","validation":{"boolean":{"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Float Field":{"summary":"Float Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Items Weight","description":"This field stores the total weight (in kilograms) of the items in the wishlist.","slug":"items_weight","field_type":"float","validation":{"float":{"min_value":0,"max_value":null,"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Integer Field":{"summary":"Integer Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Items Count","description":"This field stores the total count of items in the wishlist.","slug":"items_count","field_type":"integer","validation":{"integer":{"min_value":null,"max_value":null,"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"String Field":{"summary":"String Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Name","description":"This field stores the name of the wishlist.","slug":"name","field_type":"string","validation":{"string":{"min_length":3,"max_length":128,"regex":null,"allow_null_values":true,"immutable":false,"unique":"no","unique_case_insensitivity":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Any Field":{"summary":"Any Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Metadata","description":"This field stores arbitrary metadata as a JSON object.","slug":"metadata","field_type":"any","validation":{"any":{"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"List Field":{"summary":"List Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Tags","description":"This field stores a list of tags for the wishlist.","slug":"tags","field_type":"list","validation":{"list":{"allow_null_values":true,"immutable":false,"min_length":null,"max_length":null,"allowed_type":"string"}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get OpenAPI Specification

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get OpenAPI Specification"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/extensions/specifications/openapi"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Generates an OpenAPI specification based on the Custom APIs and Custom Fields configured for the current store.
This dynamically generated specification provides typed schemas for the `/v2/extensions/` endpoints.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","description":"The OpenAPI specification in JSON format.","additionalProperties":true}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## List Custom APIs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Custom APIs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/extensions/custom-apis"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of Custom APIs

## Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) Custom APIs:

| Attribute           | Operators                     | Example                                       |
|---------------------|-------------------------------|-----------------------------------------------|
| `id`                | `lt`,`le`,`eq`,`gt`,`ge`,`in` | `eq(id,7e067539-6f6c-46e1-8c55-940031b36c6a)` |
| `created_at`        | `lt`,`le`,`eq`,`gt`,`ge`      | `ge(created_at,2024-04-29T00:00:00.000Z)`     |
| `updated_at`        | `lt`,`le`,`eq`,`gt`,`ge`      | `le(updated_at,2024-04-29T00:00:00.000Z)`     |
| `api_type`          | `eq`,`like`,`in`              | `like(api_type,wishlist*)`                    |
| `description`       | `eq`,`like`                   | `like(description,*list*)`                    |
| `name`              | `eq`,`like`                   | `eq(name,"Wishlist")`                         |
| `slug`              | `eq`,`like`,`in`              | `like(slug,*lists)`                           |
| `presentation.page` | `ilike`                       | `ilike(presentation.page,Home)`               |

## Sorting
The following attributes are available for sorting. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with `-`, for example, `-updated_at`. The default sort order is `created_at` in descending order.
- `id`
- `created_at`
- `updated_at`
- `api_type`
- `name`
- `slug`

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":0}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"description":"Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.","schema":{"type":"string","format":"string","example":"eq(name,\"My Wishlist\")"}},{"name":"sort","in":"query","description":"Specifies the order in which Custom APIs will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).\n","required":false,"schema":{"type":"string","default":"-created_at","enum":["id","-id","created_at","-created_at","updated_at","-updated_at","api_type","-api_type","name","-name","slug","-slug"],"example":"id","x-enumDescriptions":{"id":"Sort by UUID string in ascending order","-id":"Sort by UUID string in descending order","created_at":"Sort chronologically from oldest to newest creation date","-created_at":"Sort chronologically from newest to oldest creation date","updated_at":"Sort chronologically from oldest to newest update date","-updated_at":"Sort chronologically from newest to oldest update date","api_type":"Sort API types alphabetically (A-Z)","-api_type":"Sort API types reverse alphabetically (Z-A)","name":"Sort names alphabetically (A-Z)","-name":"Sort names reverse alphabetically (Z-A)","slug":"Sort slugs alphabetically (A-Z)","-slug":"Sort slugs reverse alphabetically (Z-A)"}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List of Custom APIs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom API.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api` for Custom APIs.","const":"custom_api"},"name":{"type":"string","description":"Specifies the name of this Custom API.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom API.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.\n","pattern":"^[a-z0-9_-]{1,63}$"},"api_type":{"type":"string","description":"Specifies a unique API type for this Custom API. Entries for this API will use this value for their `type` field. This field must be suffixed with `_ext` to distinguish it from built in APIs.\n","pattern":"^[a-z0-9_]{1,59}_ext$"},"allow_upserts":{"type":"boolean","description":"Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn't exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.\n","default":false},"presentation":{"type":"object","description":"Optional presentation options for the Custom API.","properties":{"page":{"type":["string","null"],"description":"The page where this Custom API should be presented. The available values depend on the deployment and may change."},"section":{"type":["string","null"],"description":"The section within the page. Can only be set when `page` is also set."}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},"relationships":{"type":"object","properties":{"parent_apis":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API. When the `type` of an object is set to `api_location` then `id` must be `/v2/extensions`.\nWhen the `type` of an object is set to `custom_api`, then `id` must be that of a Custom API that results in a relationship that does not have a depth exceeding 2 and does not result in a cycle.\n","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of parent relationship, can be `custom_api` or `api_location`.","enum":["custom_api","api_location"]}}}}}}},"title":"CustomAPIRelationships"}},"title":"CustomAPI"}},"meta":{"type":"object","properties":{"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results for the entire collection."},"total_method":{"type":"string","description":"The method used to calculate the total number results.","enum":["exact","lower_bound","observed"],"x-enumDescriptions":{"exact":"Indicates that the total is an exact count of results","lower_bound":"When there are more than 10,000 results, we stop counting at 10,000 and report that the count is a lower_bound.","observed":"Will indicate if there is at least one more result past the current page, this is the highest performing option as it doesn't require an extra call."}}}},"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records for all pages.","example":100},"offset":{"type":"integer","description":"The current offset by number of pages.","example":0},"current":{"type":"integer","description":"The current number of pages.","example":1},"total":{"type":"integer","description":"The total number of pages.","example":1}}}},"title":"PaginationMeta"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"first":{"description":"Always the first page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"last":{"description":"Always `null` if there is only one page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"next":{"description":"Always `null` if there is only one page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"},"prev":{"description":"Always `null` if on the first page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"}},"title":"PaginationLinks"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Bad Filter":{"summary":"Invalid field specified for filter","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Invalid filter: unknown field [version] specified in search filter, allowed fields are [api_type created_at description id name slug updated_at]\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## List Custom API Entries

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Custom API Entries"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/entries"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of Custom API Entries

## Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) all Custom API Entries:

| Attribute     | Operators                     | Example                                       |
|---------------|-------------------------------|-----------------------------------------------|
| `id`          | `lt`,`le`,`eq`,`gt`,`ge`,`in` | `eq(id,859aeba1-03c2-4822-bd4c-89afce93d7eb)` |
| `created_at`  | `lt`,`le`,`eq`,`gt`,`ge`      | `ge(created_at,2024-04-29T00:00:00.000Z)`     |
| `updated_at`  | `lt`,`le`,`eq`,`gt`,`ge`      | `le(updated_at,2024-04-29T00:00:00.000Z)`     |

The following operators and attributes may be available for filtering Custom API Entries depending on how the [Custom Fields](/docs/api/commerce-extensions/create-a-custom-field) for that Custom API are configured.

| Field type | Operators                                                 |
|------------|-----------------------------------------------------------|
| `string`   | `lt`,`le`,`eq`,`gt`,`ge`,`in`,`is_null`,`like`            |
| `integer`  | `lt`,`le`,`eq`,`gt`,`ge`,`in`,`is_null`                   |
| `float`    | `lt`,`le`,`gt`,`ge`,`in`,`is_null`                        |
| `boolean`  | `eq`,`is_null`                                            |
| `list`     | `contains`,`contains_any`,`is_null`,`contains_all`(typed) |

Given there is a Custom Field with `"slug": "name"` and `"field_type": "string"`.

When you get all Custom API Entries with query parameter: `?filter=like(name,*wish*)`.

Then you will get all Custom API Entries where `name` contains the string `wish`.

:::warn

For performance reasons, the `is_null` search operator will **NOT** match entries for a custom_field where the custom_entry was last updated before the custom_field existed. Updating the entry will cause the field to exist and match properly.

:::

## Sorting
The following attributes are available for sorting. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with `-`, for example, `-updated_at`. The default sort order is `created_at` in descending order.
- `id`
- `created_at`
- `updated_at`

## Query Optimization

When working with large data sets, the following practices help reduce query latency and avoid timeouts.

### Choose the right `page[total_method]`

By default, every list request calculates a `lower_bound` total, which counts up to 10,000 matching records. If you only need to know whether a next page exists (for example, in an infinite-scroll UI), set `page[total_method]=observed`. This skips the full count and only checks for one record beyond the current page, which can significantly reduce response times on large data sets.

| Method         | Behavior                                                                 | Best for                                   |
|----------------|---------------------------------------------------------------------------|--------------------------------------------|
| `lower_bound`  | Counts up to 10,000 records; reports exact total or indicates lower bound | Displaying a total count to users          |
| `observed`     | Checks only if a next page exists beyond the current offset and limit     | Infinite scroll, cursor-style pagination   |

### Skip sorting when order doesn't matter

Setting `sort=null` disables sorting entirely. If your use case does not require a specific order (for example, background sync jobs), this avoids the overhead of ordering results and can improve throughput.

### Narrow your filters

Queries that filter on Custom Fields are more efficient when the filter is selective. Prefer exact-match operators (`eq`, `in`) over range or wildcard operators (`like`, `lt`/`le`/`gt`/`ge`) where possible, and combine multiple filters to reduce the result set early.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":0}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"page[total_method]","description":"The method used to calculate the total number of matching entries in the response.\n","in":"query","required":false,"schema":{"type":"string","enum":["lower_bound","observed"],"default":"lower_bound","x-enumDescriptions":{"lower_bound":"Restricts the count of records to at most 10,000. If there are <=10,000 records, the response will indicate it is an exact total, otherwise it will indicate lower_bound.\n","observed":"Restricts the count of record to check only if there is a next page. For example if your page[offset] is 0, and page[limit] is 25, and there are 200 records, then with page[total_method]=observed, the response will indicate there are 26, so that the client knows there are more records.\n"}}},{"name":"filter","in":"query","required":false,"description":"Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.","schema":{"type":"string","format":"string","example":"eq(name,\"My Wishlist\")"}},{"name":"sort","in":"query","description":"Specifies the order in which Custom API Entries will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).\n","required":false,"schema":{"type":"string","default":"-created_at","enum":["id","-id","created_at","-created_at","updated_at","-updated_at","null"],"example":"id","x-enumDescriptions":{"id":"Sort by UUID string in ascending order","-id":"Sort by UUID string in descending order","created_at":"Sort chronologically from oldest to newest creation date","-created_at":"Sort chronologically from newest to oldest creation date","updated_at":"Sort chronologically from oldest to newest update date","-updated_at":"Sort chronologically from newest to oldest update date","null":"Does not apply any sorting (may improve performance if you don't care about sort)"}}},{"name":"timeout","description":"Specifies how long in milliseconds the request should be allowed to take. The service will return a 422 if the request takes longer than the specified timeout.\n","in":"query","schema":{"type":"integer","minimum":1,"maximum":20000}},{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List of Custom API Entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Entry.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use the `api_type` of the [Custom API](/docs/api/commerce-extensions/create-a-custom-api) for Custom API Entry.\n","examples":["wishlist_ext"]},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Entry.","example":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"allOf":[{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},{"type":"object","properties":{"data_size":{"type":"integer","description":"The approximate size of the data, used to enforce size limits as this value must not exceed 64 KiB. The exact calculation is intentionally unspecified to allow storage optimizations. This value will always be less than or equal to the size of the JSON representation of all field values.\n","default":0,"example":6},"resource_version":{"type":"integer","description":"A unique identifier representing the current version of the resource. When the resource changes, the `resource_version` value will also change.\n","default":0,"example":4},"etag_id":{"type":"string","description":"A unique identifier representing the current version of the resource that is a hashed string. When the resource changes, the `etag_id` will also change.\n","example":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"}}}]}},"title":"CustomAPIEntry"}},"meta":{"type":"object","properties":{"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results for the entire collection."},"total_method":{"type":"string","description":"The method used to calculate the total number results.","enum":["exact","lower_bound","observed"],"x-enumDescriptions":{"exact":"Indicates that the total is an exact count of results","lower_bound":"When there are more than 10,000 results, we stop counting at 10,000 and report that the count is a lower_bound.","observed":"Will indicate if there is at least one more result past the current page, this is the highest performing option as it doesn't require an extra call."}}}},"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records for all pages.","example":100},"offset":{"type":"integer","description":"The current offset by number of pages.","example":0},"current":{"type":"integer","description":"The current number of pages.","example":1},"total":{"type":"integer","description":"The total number of pages.","example":1}}}},"title":"PaginationMeta"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"first":{"description":"Always the first page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"last":{"description":"Always `null` if there is only one page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"next":{"description":"Always `null` if there is only one page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"},"prev":{"description":"Always `null` if on the first page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"}},"title":"PaginationLinks"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Bad Filter":{"summary":"Invalid field specified for filter","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Invalid filter: unknown field [version] specified in search filter, allowed fields are [api_type created_at description id name slug updated_at]\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}},"403":{"description":"Forbidden. You do not have permission to access this resource.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Forbidden Access":{"summary":"Forbidden error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Forbidden\",\n      \"status\": \"403\",\n      \"detail\": \"You do not have permission to access this resource.\"\n    }\n  ]\n}\n"}}}}},"422":{"description":"Unprocessable Content. The server couldn't satisfy your request, most likely due to a timeout.\n","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Unprocessable Content":{"summary":"Unprocessable content","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Unprocessable Content\",\n      \"status\": \"422\",\n      \"detail\": \"request timed out after 20000 ms.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## List Custom Fields

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Custom Fields"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of Custom Fields

## Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) Custom Fields:

| Attribute     | Operators                     | Example                                       |
|---------------|-------------------------------|-----------------------------------------------|
| `id`          | `lt`,`le`,`eq`,`gt`,`ge`,`in` | `eq(id,859aeba1-03c2-4822-bd4c-89afce93d7eb)` |
| `created_at`  | `lt`,`le`,`eq`,`gt`,`ge`      | `ge(created_at,2024-04-29T00:00:00.000Z)`     |
| `updated_at`  | `lt`,`le`,`eq`,`gt`,`ge`      | `le(updated_at,2024-04-29T00:00:00.000Z)`     |
| `description` | `eq`,`like`                   | `like(description,*confidential*)`            |
| `field_type`  | `eq`,`in`                     | `eq(field_type,string)`                       |
| `name`        | `eq`,`like`                   | `eq(name,"Last Name")`                        |
| `slug`        | `eq`,`like`,`in`              | `like(slug,*private*)`                        |

## Sorting
The following attributes are available for sorting. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with `-`, for example, `-updated_at`. The default sort order is `created_at` in descending order.
- `id`
- `created_at`
- `updated_at`
- `field_type`
- `name`
- `slug`

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":0}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"description":"Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.","schema":{"type":"string","format":"string","example":"eq(name,\"My Wishlist\")"}},{"name":"sort","in":"query","description":"Specifies the order in which Custom Fields will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).\n","required":false,"schema":{"type":"string","default":"-created_at","enum":["id","-id","created_at","-created_at","updated_at","-updated_at","field_type","-field_type","name","-name","slug","-slug"],"example":"id","x-enumDescriptions":{"id":"Sort by UUID string in ascending order","-id":"Sort by UUID string in descending order","created_at":"Sort chronologically from oldest to newest creation date","-created_at":"Sort chronologically from newest to oldest creation date","updated_at":"Sort chronologically from oldest to newest update date","-updated_at":"Sort chronologically from newest to oldest update date","field_type":"Sort field types alphabetically (A-Z)","-field_type":"Sort field types reverse alphabetically (Z-A)","name":"Sort names alphabetically (A-Z)","-name":"Sort names reverse alphabetically (Z-A)","slug":"Sort slugs alphabetically (A-Z)","-slug":"Sort slugs reverse alphabetically (Z-A)"}}},{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List of Custom Fields","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCustomField"},{"description":"The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. This provides maximum flexibility for storing complex or varying data structures.\n\n**Important:** When updating an entry, the `any` field value is completely replaced, not merged. For example, if a field contains `{\"a\": 1, \"b\": 2}` and you update it with `{\"a\": 99}`, the result will be `{\"a\": 99}` (not `{\"a\": 99, \"b\": 2}`). Standard partial update behavior still applies at the entry level: if you omit the field entirely from an update request, the existing value is preserved.\n\n**Note:** Filtering is not supported on `any` fields.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCustomField"},{"description":"The `list` field type allows storing an array of primitive values (strings, integers, booleans, floats, or null). The list can contain up to 1000 elements.\n\n### Filtering\n\nList fields support the following filter operators:\n\n**List Content Operators** (operate on the entire list):\n- `contains(field, value)` - matches entries where the list contains the specified value\n- `contains_any(field, value1, value2, ...)` - matches entries where the list contains any of the specified values\n- `contains_all(field, value1, value2, ...)` - matches entries where the list contains all of the specified values (**requires `allowed_type` to not be `any`**)\n- `is_null(field)` - matches entries where the list field is null\n\n**Index-Based Access** (access specific elements by position):\n- `eq(field[index], value)` - matches entries where the element at the specified index equals the value\n- `like(field[index], pattern)` - matches entries where the string element at the index matches the pattern\n- `in(field[index], value1, value2, ...)` - matches entries where the element at the index is one of the specified values\n- `is_null(field[index])` - matches entries where the element at the index is null\n- `lt`, `le`, `gt`, `ge(field[index], value)` - relational comparisons (**requires `allowed_type` to not be `any`**)\n\nIndex must be a non-negative integer from 0 to 999. Negative indices are not supported.\n\n**Length Access** (filter by array length):\n- `eq(field.length, value)` - matches entries where the list has exactly the specified length\n- `lt(field.length, value)`, `le(field.length, value)` - matches entries where the list length is less than (or equal to) the value\n- `gt(field.length, value)`, `ge(field.length, value)` - matches entries where the list length is greater than (or equal to) the value\n- `in(field.length, value1, value2, ...)` - matches entries where the list length is one of the specified values\n\n### Typed Lists vs Untyped Lists\n\nWhen `allowed_type` is set to a specific type (e.g., `\"string\"`, `\"integer\"`), additional operators become available:\n- `contains_all` - efficiently matches all specified values using exact type comparison\n- Relational operators (`lt`, `le`, `gt`, `ge`) on index access - compare values with proper type handling\n\nWhen `allowed_type` is `\"any\"` (the default), these operators are not available because type coercion would make comparisons unreliable.\n\n### Type Coercion (Untyped Lists)\n\nFor lists with `allowed_type: \"any\"`, filter operators use type coercion to match values:\n- `contains(field, 1)` matches both integer `1` and string `\"1\"`\n- `contains(field, true)` matches both boolean `true` and string `\"true\"`\n- `eq(field[0], 1)` matches both integer `1` and string `\"1\"` at index 0\n\n### Type Mismatch Behavior (Typed Lists)\n\nFor operators that require exact type matching (`contains_all`, `in` on typed fields), filtering with a value that cannot be converted to the `allowed_type` returns a 400 error. For example, `contains_all(field, \"foo\")` on an integer list returns an error because `\"foo\"` cannot be converted to an integer.\n\nFor operators that use type coercion (`contains`, `contains_any`), filtering with a non-matching type returns zero results. For example, `contains(field, \"foo\")` on an integer list returns no matches because the string `\"foo\"` doesn't match any integers in the list.\n\n**Note:** Float elements in lists are not reliably filterable with `eq()` due to floating-point precision issues.\n\n**Note:** If a field slug matches the index access pattern (e.g., `myfield[0]`) or length access pattern (e.g., `myfield.length`), filtering on that field may not work as expected. To avoid conflicts, use only lowercase letters, numbers, underscores, and hyphens in field slugs.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCustomField"}],"discriminator":{"propertyName":"field_type","mapping":{"boolean":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCustomField"},"float":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCustomField"},"integer":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCustomField"},"string":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCustomField"},"any":{"description":"The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. This provides maximum flexibility for storing complex or varying data structures.\n\n**Important:** When updating an entry, the `any` field value is completely replaced, not merged. For example, if a field contains `{\"a\": 1, \"b\": 2}` and you update it with `{\"a\": 99}`, the result will be `{\"a\": 99}` (not `{\"a\": 99, \"b\": 2}`). Standard partial update behavior still applies at the entry level: if you omit the field entirely from an update request, the existing value is preserved.\n\n**Note:** Filtering is not supported on `any` fields.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCustomField"},"list":{"description":"The `list` field type allows storing an array of primitive values (strings, integers, booleans, floats, or null). The list can contain up to 1000 elements.\n\n### Filtering\n\nList fields support the following filter operators:\n\n**List Content Operators** (operate on the entire list):\n- `contains(field, value)` - matches entries where the list contains the specified value\n- `contains_any(field, value1, value2, ...)` - matches entries where the list contains any of the specified values\n- `contains_all(field, value1, value2, ...)` - matches entries where the list contains all of the specified values (**requires `allowed_type` to not be `any`**)\n- `is_null(field)` - matches entries where the list field is null\n\n**Index-Based Access** (access specific elements by position):\n- `eq(field[index], value)` - matches entries where the element at the specified index equals the value\n- `like(field[index], pattern)` - matches entries where the string element at the index matches the pattern\n- `in(field[index], value1, value2, ...)` - matches entries where the element at the index is one of the specified values\n- `is_null(field[index])` - matches entries where the element at the index is null\n- `lt`, `le`, `gt`, `ge(field[index], value)` - relational comparisons (**requires `allowed_type` to not be `any`**)\n\nIndex must be a non-negative integer from 0 to 999. Negative indices are not supported.\n\n**Length Access** (filter by array length):\n- `eq(field.length, value)` - matches entries where the list has exactly the specified length\n- `lt(field.length, value)`, `le(field.length, value)` - matches entries where the list length is less than (or equal to) the value\n- `gt(field.length, value)`, `ge(field.length, value)` - matches entries where the list length is greater than (or equal to) the value\n- `in(field.length, value1, value2, ...)` - matches entries where the list length is one of the specified values\n\n### Typed Lists vs Untyped Lists\n\nWhen `allowed_type` is set to a specific type (e.g., `\"string\"`, `\"integer\"`), additional operators become available:\n- `contains_all` - efficiently matches all specified values using exact type comparison\n- Relational operators (`lt`, `le`, `gt`, `ge`) on index access - compare values with proper type handling\n\nWhen `allowed_type` is `\"any\"` (the default), these operators are not available because type coercion would make comparisons unreliable.\n\n### Type Coercion (Untyped Lists)\n\nFor lists with `allowed_type: \"any\"`, filter operators use type coercion to match values:\n- `contains(field, 1)` matches both integer `1` and string `\"1\"`\n- `contains(field, true)` matches both boolean `true` and string `\"true\"`\n- `eq(field[0], 1)` matches both integer `1` and string `\"1\"` at index 0\n\n### Type Mismatch Behavior (Typed Lists)\n\nFor operators that require exact type matching (`contains_all`, `in` on typed fields), filtering with a value that cannot be converted to the `allowed_type` returns a 400 error. For example, `contains_all(field, \"foo\")` on an integer list returns an error because `\"foo\"` cannot be converted to an integer.\n\nFor operators that use type coercion (`contains`, `contains_any`), filtering with a non-matching type returns zero results. For example, `contains(field, \"foo\")` on an integer list returns no matches because the string `\"foo\"` doesn't match any integers in the list.\n\n**Note:** Float elements in lists are not reliably filterable with `eq()` due to floating-point precision issues.\n\n**Note:** If a field slug matches the index access pattern (e.g., `myfield[0]`) or length access pattern (e.g., `myfield.length`), filtering on that field may not work as expected. To avoid conflicts, use only lowercase letters, numbers, underscores, and hyphens in field slugs.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCustomField"}}},"title":"CustomField"}},"meta":{"type":"object","properties":{"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results for the entire collection."},"total_method":{"type":"string","description":"The method used to calculate the total number results.","enum":["exact","lower_bound","observed"],"x-enumDescriptions":{"exact":"Indicates that the total is an exact count of results","lower_bound":"When there are more than 10,000 results, we stop counting at 10,000 and report that the count is a lower_bound.","observed":"Will indicate if there is at least one more result past the current page, this is the highest performing option as it doesn't require an extra call."}}}},"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records for all pages.","example":100},"offset":{"type":"integer","description":"The current offset by number of pages.","example":0},"current":{"type":"integer","description":"The current number of pages.","example":1},"total":{"type":"integer","description":"The total number of pages.","example":1}}}},"title":"PaginationMeta"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"first":{"description":"Always the first page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"last":{"description":"Always `null` if there is only one page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"next":{"description":"Always `null` if there is only one page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"},"prev":{"description":"Always `null` if on the first page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"}},"title":"PaginationLinks"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Bad Filter":{"summary":"Invalid field specified for filter","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Invalid filter: unknown field [version] specified in search filter, allowed fields are [api_type created_at description id name slug updated_at]\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Update a Custom API

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Custom API"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a Custom API

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api` for Custom APIs.","const":"custom_api"},"name":{"type":"string","description":"Specifies the name of this Custom API.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom API.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.\n","pattern":"^[a-z0-9_-]{1,63}$"},"allow_upserts":{"type":"boolean","description":"Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn't exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.\n","default":false},"presentation":{"type":"object","description":"Optional presentation options for the Custom API.","properties":{"page":{"type":["string","null"],"description":"The page where this Custom API should be presented. The available values depend on the deployment and may change."},"section":{"type":["string","null"],"description":"The section within the page. Can only be set when `page` is also set.","maxLength":64}}},"relationships":{"type":"object","properties":{"parent_apis":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API. When the `type` of an object is set to `api_location` then `id` must be `/v2/extensions`.\nWhen the `type` of an object is set to `custom_api`, then `id` must be that of a Custom API that results in a relationship that does not have a depth exceeding 2 and does not result in a cycle.\n","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of parent relationship, can be `custom_api` or `api_location`.","enum":["custom_api","api_location"]}}}}}}},"title":"CustomAPIRelationships"}}}}},"examples":{"Update Example":{"summary":"Update a Custom API","value":{"data":{"type":"custom_api","name":"Wishlists","description":"Specifies the description for this Custom API.","slug":"wishlists","relationships":{"parent_apis":{"data":[{"id":"652e39d8-d613-493e-8c20-fef99ad6327a","type":"custom_api"}]}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Custom API","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom API.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api` for Custom APIs.","const":"custom_api"},"name":{"type":"string","description":"Specifies the name of this Custom API.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom API.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a unique slug identifier for the Custom API. The API Entries for the created Custom API will be accessible at the location `/v2/extensions/<slug>`.\n","pattern":"^[a-z0-9_-]{1,63}$"},"api_type":{"type":"string","description":"Specifies a unique API type for this Custom API. Entries for this API will use this value for their `type` field. This field must be suffixed with `_ext` to distinguish it from built in APIs.\n","pattern":"^[a-z0-9_]{1,59}_ext$"},"allow_upserts":{"type":"boolean","description":"Controls whether upsert operations are allowed for Custom API Entries via the `PUT` method. When set to `true`, it allows the creation of new Custom API Entries using `PUT` if the record doesn't exist, and updates the existing record if it does. When `false`, `PUT` requests can only update existing entries.\n","default":false},"presentation":{"type":"object","description":"Optional presentation options for the Custom API.","properties":{"page":{"type":["string","null"],"description":"The page where this Custom API should be presented. The available values depend on the deployment and may change."},"section":{"type":["string","null"],"description":"The section within the page. Can only be set when `page` is also set."}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},"relationships":{"type":"object","properties":{"parent_apis":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API. When the `type` of an object is set to `api_location` then `id` must be `/v2/extensions`.\nWhen the `type` of an object is set to `custom_api`, then `id` must be that of a Custom API that results in a relationship that does not have a depth exceeding 2 and does not result in a cycle.\n","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of parent relationship, can be `custom_api` or `api_location`.","enum":["custom_api","api_location"]}}}}}}},"title":"CustomAPIRelationships"}},"title":"CustomAPI"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Duplicate Custom API":{"summary":"Duplicate Custom API","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_api with the given api_type already exists\"\n    }\n  ]\n}\n"},"Duplicate Custom Field":{"summary":"Duplicate Custom Field","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_field with the given slug already exists\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Update a Custom API Entry

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Custom API Entry"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/entries/{custom-api-entry-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a Custom API Entry

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"If-Match","description":"When If-Match is set, the value must be W/\"{etag_id}\". If the value of the header matches, the request completes. If not, HTTP 412 Precondition Failed is returned.\n","in":"header","required":true,"schema":{"type":"string","format":"string"}},{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"custom-api-entry-id","description":"The unique identifier of the Custom API Entry.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"7e067539-6f6c-46e1-8c55-940031b36c6a"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type"],"additionalProperties":true,"properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use the `api_type` of the [Custom API](/docs/api/commerce-extensions/create-a-custom-api) for Custom API Entry.\n","examples":["wishlist_ext"]}}}}},"examples":{"Update Example":{"summary":"Update a Wishlist","value":{"data":{"type":"wishlist_ext","name":"My Wishlist","items_count":1,"keep_purchased":false,"tags":["birthday","gifts","priority"]}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Custom API Entry","headers":{"ETag":{"description":"A unique identifier representing the current version of the resource. When the resource changes, the ETag value will also change. The ETag hash will be the same value as `etag_id`, and is marked as a weak entity tag string. For example: etag: W/\"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\", etag_id: 5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Entry.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use the `api_type` of the [Custom API](/docs/api/commerce-extensions/create-a-custom-api) for Custom API Entry.\n","examples":["wishlist_ext"]},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Entry.","example":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"allOf":[{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},{"type":"object","properties":{"data_size":{"type":"integer","description":"The approximate size of the data, used to enforce size limits as this value must not exceed 64 KiB. The exact calculation is intentionally unspecified to allow storage optimizations. This value will always be less than or equal to the size of the JSON representation of all field values.\n","default":0,"example":6},"resource_version":{"type":"integer","description":"A unique identifier representing the current version of the resource. When the resource changes, the `resource_version` value will also change.\n","default":0,"example":4},"etag_id":{"type":"string","description":"A unique identifier representing the current version of the resource that is a hashed string. When the resource changes, the `etag_id` will also change.\n","example":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"}}}]}},"title":"CustomAPIEntry"}}},"examples":{"Custom API Entry":{"summary":"Default Wishlist","value":{"data":{"id":"7e067539-6f6c-46e1-8c55-940031b36c6a","type":"wishlist_ext","name":"My Wishlist","items_count":0,"keep_purchased":false,"tags":["birthday","gifts"],"links":{"self":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"},"resource_version\"":0,"data_size\"":6,"etag_id\"":"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9"}}}}}}}},"201":{"description":"A Custom API Entry","headers":{"ETag":{"description":"A unique identifier representing the current version of the resource. When the resource changes, the ETag value will also change. The ETag hash will be the same value as `etag_id`, and is marked as a weak entity tag string. For example: etag: W/\"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\", etag_id: 5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Entry.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use the `api_type` of the [Custom API](/docs/api/commerce-extensions/create-a-custom-api) for Custom API Entry.\n","examples":["wishlist_ext"]},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Entry.","example":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"allOf":[{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},{"type":"object","properties":{"data_size":{"type":"integer","description":"The approximate size of the data, used to enforce size limits as this value must not exceed 64 KiB. The exact calculation is intentionally unspecified to allow storage optimizations. This value will always be less than or equal to the size of the JSON representation of all field values.\n","default":0,"example":6},"resource_version":{"type":"integer","description":"A unique identifier representing the current version of the resource. When the resource changes, the `resource_version` value will also change.\n","default":0,"example":4},"etag_id":{"type":"string","description":"A unique identifier representing the current version of the resource that is a hashed string. When the resource changes, the `etag_id` will also change.\n","example":"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"}}}]}},"title":"CustomAPIEntry"}}},"examples":{"Custom API Entry":{"summary":"Default Wishlist","value":{"data":{"id":"7e067539-6f6c-46e1-8c55-940031b36c6a","type":"wishlist_ext","name":"My Wishlist","items_count":0,"keep_purchased":false,"tags":["birthday","gifts"],"links":{"self":"/v2/extensions/wishlists/7e067539-6f6c-46e1-8c55-940031b36c6a"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"},"resource_version\"":0,"data_size\"":6,"etag_id\"":"5feceb66ffc86f38d952786c6d696c79c2dbc239dd4e91b46729d73a27fb57e9"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"403":{"description":"Forbidden. You do not have permission to access this resource.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Forbidden Access":{"summary":"Forbidden error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Forbidden\",\n      \"status\": \"403\",\n      \"detail\": \"You do not have permission to access this resource.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Duplicate Custom API":{"summary":"Duplicate Custom API","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_api with the given api_type already exists\"\n    }\n  ]\n}\n"},"Duplicate Custom Field":{"summary":"Duplicate Custom Field","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_field with the given slug already exists\"\n    }\n  ]\n}\n"}}}}},"412":{"description":"Precondition Failed.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Precondition Failed":{"summary":"Provided ETag does not match the current ETag.","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Precondition Failed\",\n      \"status\": \"412\",\n      \"detail\": \"The provided ETag 'W/\\\"4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a\\\"', does not match the current ETag 'W/\\\"ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d\\\"'.\"\n    }\n  ]\n}\n"}}}}},"413":{"description":"Payload Too Large. The total size of a Custom API Entry must not exceed 64KB.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Payload Too Large":{"summary":"Requested entity too large","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Request Entity Too Large\",\n      \"status\": \"413\",\n      \"detail\": \"Maximum entry size reached.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}},"503":{"description":"The service is temporarily unavailable. This request can be safely retried.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Service Unavailable":{"summary":"Service Unavailable","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"An unknown error occurred\",\n      \"status\": \"503\",\n      \"title\": \"Service Unavailable\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Update a Custom Field

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Custom Field"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings/extensions/custom-apis/{custom-api-id}/fields/{custom-field-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a Custom Field

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-id","description":"The unique identifier of the Custom API.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},{"name":"custom-field-id","description":"The unique identifier of the Custom Field.","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"859aeba1-03c2-4822-bd4c-89afce93d7eb"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type"],"oneOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseUpdateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanUpdateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseUpdateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatUpdateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseUpdateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerUpdateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseUpdateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":1},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringUpdateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseUpdateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyUpdateCustomField"},{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be value as the key in the JSON Object in all entries.\n","minLength":1,"maxLength":63},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}}},"title":"BaseUpdateCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListUpdateCustomField"}]}}},"examples":{"Update Boolean Field":{"summary":"Update a Boolean Field","value":{"data":{"type":"custom_field","name":"Keep Purchased Items","description":"This field stores whether or not to keep purchased items on the wishlist.","slug":"keep_purchased","validation":{"boolean":{"allow_null_values":true,"immutable":false}}}}},"Update Float Field":{"summary":"Update a Float Field","value":{"data":{"type":"custom_field","name":"Items Weight","description":"This field stores the total weight (in kilograms) of the items in the wishlist.","slug":"items_weight","validation":{"float":{"min_value":0,"max_value":null,"allow_null_values":true,"immutable":false}}}}},"Update Integer Field":{"summary":"Update a Integer Field","value":{"data":{"type":"custom_field","name":"Items Count","description":"This field stores the total count of items in the wishlist.","slug":"items_count","validation":{"integer":{"min_value":0,"max_value":null,"allow_null_values":true,"immutable":false}}}}},"Update String Field":{"summary":"Update a String Field","value":{"data":{"type":"custom_field","name":"Name","description":"This field stores the name of the wishlist.","slug":"name","validation":{"string":{"min_length":3,"max_length":128,"regex":null,"allow_null_values":true,"immutable":false}}}}},"Update Any Field":{"summary":"Update an Any Field","value":{"data":{"type":"custom_field","name":"Metadata","description":"This field stores arbitrary metadata as a JSON object.","validation":{"any":{"allow_null_values":true,"immutable":false}}}}},"Update List Field":{"summary":"Update a List Field","value":{"data":{"type":"custom_field","name":"Tags","description":"This field stores a list of tags for the wishlist.","validation":{"list":{"allow_null_values":true,"immutable":false,"min_length":0,"max_length":100}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Custom Field","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCustomField"},{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCustomField"},{"description":"The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. This provides maximum flexibility for storing complex or varying data structures.\n\n**Important:** When updating an entry, the `any` field value is completely replaced, not merged. For example, if a field contains `{\"a\": 1, \"b\": 2}` and you update it with `{\"a\": 99}`, the result will be `{\"a\": 99}` (not `{\"a\": 99, \"b\": 2}`). Standard partial update behavior still applies at the entry level: if you omit the field entirely from an update request, the existing value is preserved.\n\n**Note:** Filtering is not supported on `any` fields.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCustomField"},{"description":"The `list` field type allows storing an array of primitive values (strings, integers, booleans, floats, or null). The list can contain up to 1000 elements.\n\n### Filtering\n\nList fields support the following filter operators:\n\n**List Content Operators** (operate on the entire list):\n- `contains(field, value)` - matches entries where the list contains the specified value\n- `contains_any(field, value1, value2, ...)` - matches entries where the list contains any of the specified values\n- `contains_all(field, value1, value2, ...)` - matches entries where the list contains all of the specified values (**requires `allowed_type` to not be `any`**)\n- `is_null(field)` - matches entries where the list field is null\n\n**Index-Based Access** (access specific elements by position):\n- `eq(field[index], value)` - matches entries where the element at the specified index equals the value\n- `like(field[index], pattern)` - matches entries where the string element at the index matches the pattern\n- `in(field[index], value1, value2, ...)` - matches entries where the element at the index is one of the specified values\n- `is_null(field[index])` - matches entries where the element at the index is null\n- `lt`, `le`, `gt`, `ge(field[index], value)` - relational comparisons (**requires `allowed_type` to not be `any`**)\n\nIndex must be a non-negative integer from 0 to 999. Negative indices are not supported.\n\n**Length Access** (filter by array length):\n- `eq(field.length, value)` - matches entries where the list has exactly the specified length\n- `lt(field.length, value)`, `le(field.length, value)` - matches entries where the list length is less than (or equal to) the value\n- `gt(field.length, value)`, `ge(field.length, value)` - matches entries where the list length is greater than (or equal to) the value\n- `in(field.length, value1, value2, ...)` - matches entries where the list length is one of the specified values\n\n### Typed Lists vs Untyped Lists\n\nWhen `allowed_type` is set to a specific type (e.g., `\"string\"`, `\"integer\"`), additional operators become available:\n- `contains_all` - efficiently matches all specified values using exact type comparison\n- Relational operators (`lt`, `le`, `gt`, `ge`) on index access - compare values with proper type handling\n\nWhen `allowed_type` is `\"any\"` (the default), these operators are not available because type coercion would make comparisons unreliable.\n\n### Type Coercion (Untyped Lists)\n\nFor lists with `allowed_type: \"any\"`, filter operators use type coercion to match values:\n- `contains(field, 1)` matches both integer `1` and string `\"1\"`\n- `contains(field, true)` matches both boolean `true` and string `\"true\"`\n- `eq(field[0], 1)` matches both integer `1` and string `\"1\"` at index 0\n\n### Type Mismatch Behavior (Typed Lists)\n\nFor operators that require exact type matching (`contains_all`, `in` on typed fields), filtering with a value that cannot be converted to the `allowed_type` returns a 400 error. For example, `contains_all(field, \"foo\")` on an integer list returns an error because `\"foo\"` cannot be converted to an integer.\n\nFor operators that use type coercion (`contains`, `contains_any`), filtering with a non-matching type returns zero results. For example, `contains(field, \"foo\")` on an integer list returns no matches because the string `\"foo\"` doesn't match any integers in the list.\n\n**Note:** Float elements in lists are not reliably filterable with `eq()` due to floating-point precision issues.\n\n**Note:** If a field slug matches the index access pattern (e.g., `myfield[0]`) or length access pattern (e.g., `myfield.length`), filtering on that field may not work as expected. To avoid conflicts, use only lowercase letters, numbers, underscores, and hyphens in field slugs.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCustomField"}],"discriminator":{"propertyName":"field_type","mapping":{"boolean":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"boolean":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"BooleanCustomField"},"float":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"float":{"type":"object","properties":{"min_value":{"type":["number","null"],"description":"Specifies the minimum number that can be stored."},"max_value":{"type":["number","null"],"description":"Specifies the maximum number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"FloatCustomField"},"integer":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"integer":{"type":"object","properties":{"min_value":{"type":["integer","null"],"description":"Specifies the minimum whole number that can be stored."},"max_value":{"type":["integer","null"],"description":"Specifies the maximum whole number that can be stored."},"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false}}}}}}}],"title":"IntegerCustomField"},"string":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"string":{"type":"object","properties":{"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535,"example":1},"max_length":{"type":["integer","null"],"description":"Specifies the minimum number of characters that can be stored.","minimum":0,"maximum":65535},"regex":{"type":["string","null"],"description":"An [RE2](https://github.com/google/re2/wiki/Syntax) regular expression that used to restrict the specific characters that can be stored.\n","minLength":0,"maxLength":1024,"example":"^.+\\\\.(jpg|jpeg|png|gif|pdf)$"},"allow_null_values":{"type":"boolean","description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"unique":{"type":"string","description":"If `yes`, this prevents two Custom API entries from having the same value for this field within the Custom API. When set to `no` (the default), multiple Custom API entries may have the same value.\n","enum":["yes","no"],"default":"no"},"unique_case_insensitivity":{"type":"boolean","description":"Controls case-insensitive uniqueness for this field. Can only be set to `true` if `unique` is set to `yes`.\nIf `true`, prevents two Custom API entries from having the same value for this field within the Custom API, ignoring case differences.\nWhen set to `false` (the default), case is considered when checking for uniqueness.\nThis value can only be set during field creation and cannot be modified afterwards.\n","default":false},"immutable":{"type":"boolean","description":"When set to true, the value of this field can be specified only during POST requests and cannot be modified during PUT requests.\n","default":false}}}}}}}],"title":"StringCustomField"},"any":{"description":"The `any` field type allows storing arbitrary JSON values including objects, arrays, strings, numbers, booleans, and null. This provides maximum flexibility for storing complex or varying data structures.\n\n**Important:** When updating an entry, the `any` field value is completely replaced, not merged. For example, if a field contains `{\"a\": 1, \"b\": 2}` and you update it with `{\"a\": 99}`, the result will be `{\"a\": 99}` (not `{\"a\": 99, \"b\": 2}`). Standard partial update behavior still applies at the entry level: if you omit the field entirely from an update request, the existing value is preserved.\n\n**Note:** Filtering is not supported on `any` fields.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"any":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values for that field on Custom API Entries. When set to `false`, storing `null` values is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.","default":false},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"AnyCustomField"},"list":{"description":"The `list` field type allows storing an array of primitive values (strings, integers, booleans, floats, or null). The list can contain up to 1000 elements.\n\n### Filtering\n\nList fields support the following filter operators:\n\n**List Content Operators** (operate on the entire list):\n- `contains(field, value)` - matches entries where the list contains the specified value\n- `contains_any(field, value1, value2, ...)` - matches entries where the list contains any of the specified values\n- `contains_all(field, value1, value2, ...)` - matches entries where the list contains all of the specified values (**requires `allowed_type` to not be `any`**)\n- `is_null(field)` - matches entries where the list field is null\n\n**Index-Based Access** (access specific elements by position):\n- `eq(field[index], value)` - matches entries where the element at the specified index equals the value\n- `like(field[index], pattern)` - matches entries where the string element at the index matches the pattern\n- `in(field[index], value1, value2, ...)` - matches entries where the element at the index is one of the specified values\n- `is_null(field[index])` - matches entries where the element at the index is null\n- `lt`, `le`, `gt`, `ge(field[index], value)` - relational comparisons (**requires `allowed_type` to not be `any`**)\n\nIndex must be a non-negative integer from 0 to 999. Negative indices are not supported.\n\n**Length Access** (filter by array length):\n- `eq(field.length, value)` - matches entries where the list has exactly the specified length\n- `lt(field.length, value)`, `le(field.length, value)` - matches entries where the list length is less than (or equal to) the value\n- `gt(field.length, value)`, `ge(field.length, value)` - matches entries where the list length is greater than (or equal to) the value\n- `in(field.length, value1, value2, ...)` - matches entries where the list length is one of the specified values\n\n### Typed Lists vs Untyped Lists\n\nWhen `allowed_type` is set to a specific type (e.g., `\"string\"`, `\"integer\"`), additional operators become available:\n- `contains_all` - efficiently matches all specified values using exact type comparison\n- Relational operators (`lt`, `le`, `gt`, `ge`) on index access - compare values with proper type handling\n\nWhen `allowed_type` is `\"any\"` (the default), these operators are not available because type coercion would make comparisons unreliable.\n\n### Type Coercion (Untyped Lists)\n\nFor lists with `allowed_type: \"any\"`, filter operators use type coercion to match values:\n- `contains(field, 1)` matches both integer `1` and string `\"1\"`\n- `contains(field, true)` matches both boolean `true` and string `\"true\"`\n- `eq(field[0], 1)` matches both integer `1` and string `\"1\"` at index 0\n\n### Type Mismatch Behavior (Typed Lists)\n\nFor operators that require exact type matching (`contains_all`, `in` on typed fields), filtering with a value that cannot be converted to the `allowed_type` returns a 400 error. For example, `contains_all(field, \"foo\")` on an integer list returns an error because `\"foo\"` cannot be converted to an integer.\n\nFor operators that use type coercion (`contains`, `contains_any`), filtering with a non-matching type returns zero results. For example, `contains(field, \"foo\")` on an integer list returns no matches because the string `\"foo\"` doesn't match any integers in the list.\n\n**Note:** Float elements in lists are not reliably filterable with `eq()` due to floating-point precision issues.\n\n**Note:** If a field slug matches the index access pattern (e.g., `myfield[0]`) or length access pattern (e.g., `myfield.length`), filtering on that field may not work as expected. To avoid conflicts, use only lowercase letters, numbers, underscores, and hyphens in field slugs.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom Field.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_field` for Custom Field.","const":"custom_field"},"name":{"type":"string","description":"Specifies the name of this Custom Field.","minLength":1,"maxLength":255},"description":{"type":"string","description":"Specifies the description for this Custom Field.","minLength":0,"maxLength":255},"slug":{"type":"string","description":"Specifies a slug that must be unique within the scope of the Custom API. This slug will be the key in the JSON Object in all entries.\n\n**Recommended characters:** Use only lowercase letters, numbers, underscores, and hyphens (`[a-z0-9_-]+`). Using other characters (such as brackets `[]` or periods `.`) may cause conflicts with filter syntax and prevent filtering on the field.\n","minLength":1,"maxLength":63},"field_type":{"type":"string","description":"Specifies the type of the field. This field cannot be updated.","enum":["string","integer","boolean","float","any","list"]},"use_as_url_slug":{"type":"boolean","description":"Enabling this field will mean Custom API Entries created in this Custom API will use this value in the URL instead of the `id` attribute. In order to set this field, the field must be a string, and unique, not allow null values, no entries have been created yet, and this field cannot be set to true on another custom field. This field cannot be updated. In addition to any validation rules you create, the values must be [Unreserved URL Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3) (i.e., be alpha-numeric, or one of `-`, `.`, `_` or `~`).\n"},"presentation":{"type":"object","properties":{"sort_order":{"type":"integer","description":"Specifies the order of the field in the User Interface.","minimum":0,"maximum":1000,"default":0,"example":10}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom Field.","example":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"BaseCustomField"},{"type":"object","properties":{"validation":{"type":"object","additionalProperties":false,"properties":{"list":{"type":"object","properties":{"allow_null_values":{"type":["boolean","null"],"description":"When set to `true`, this allows `null` values as elements in the list. When set to `false`, storing `null` values in the list is not permitted.\n","default":true},"immutable":{"type":["boolean","null"],"description":"When set to `true`, prevents changing the field.\n","default":false},"min_length":{"type":["integer","null"],"description":"Specifies the minimum number of elements that must be in the list.","minimum":0,"maximum":1000},"max_length":{"type":["integer","null"],"description":"Specifies the maximum number of elements allowed in the list.","minimum":0,"maximum":1000},"allowed_type":{"type":"string","enum":["any","string","integer","boolean","float"],"description":"Specifies the primitive type that all elements in the list must be. Use \"any\" to allow mixed types.\n\n**Important:** This value cannot be changed after the field is created.\n","default":"any","example":"string"},"json_schema":{"type":["object","null"],"description":"An optional JSON Schema used to validate entry values for this field.\n","properties":{"version":{"type":"string","description":"The JSON Schema draft version. Must be \"2020-12\".","const":"2020-12"},"schema":{"type":"string","description":"A JSON-encoded string containing a valid JSON Schema Draft 2020-12 object.\nThe schema must not exceed 8 KiB in size.\nExternal `$ref` references (e.g., HTTP URLs, file paths) are not supported and will be rejected.\n","maxLength":8192}},"title":"JSONSchemaValidation"}}}}}}}],"title":"ListCustomField"}}},"title":"CustomField"}}},"examples":{"Boolean Field":{"summary":"Boolean Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Keep Purchased Items","description":"This field stores whether or not to keep purchased items on the wishlist.","slug":"keep_purchased","field_type":"boolean","validation":{"boolean":{"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Float Field":{"summary":"Float Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Items Weight","description":"This field stores the total weight (in kilograms) of the items in the wishlist.","slug":"items_weight","field_type":"float","validation":{"float":{"min_value":0,"max_value":null,"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Integer Field":{"summary":"Integer Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Items Count","description":"This field stores the total count of items in the wishlist.","slug":"items_count","field_type":"integer","validation":{"integer":{"min_value":null,"max_value":null,"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"String Field":{"summary":"String Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Name","description":"This field stores the name of the wishlist.","slug":"name","field_type":"string","validation":{"string":{"min_length":3,"max_length":128,"regex":null,"allow_null_values":true,"immutable":false,"unique":"no","unique_case_insensitivity":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"Any Field":{"summary":"Any Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Metadata","description":"This field stores arbitrary metadata as a JSON object.","slug":"metadata","field_type":"any","validation":{"any":{"allow_null_values":true,"immutable":false}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}},"List Field":{"summary":"List Field","value":{"data":{"id":"859aeba1-03c2-4822-bd4c-89afce93d7eb","type":"custom_field","name":"Tags","description":"This field stores a list of tags for the wishlist.","slug":"tags","field_type":"list","validation":{"list":{"allow_null_values":true,"immutable":false,"min_length":null,"max_length":null,"allowed_type":"string"}},"links":{"self":"/v2/settings/extensions/custom-apis/3fa85f64-5717-4562-b3fc-2c963f66afa6/fields/859aeba1-03c2-4822-bd4c-89afce93d7eb"},"meta":{"timestamps":{"created_at":"2017-01-10T11:41:19.244Z","updated_at":"2017-01-10T11:41:19.244Z"}}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Missing Name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Not Found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Duplicate Custom API":{"summary":"Duplicate Custom API","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_api with the given api_type already exists\"\n    }\n  ]\n}\n"},"Duplicate Custom Field":{"summary":"Duplicate Custom Field","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_field with the given slug already exists\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"Internal Server Error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Addresses Introduction(Customer-addresses)

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/customer-addresses/CustomerAddresses.OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Addresses Introduction"}
>
</Heading>

The Addresses API allows you to organize customer addresses. Addresses are a sub-resource of a `customer`, a customer can have multiple addresses, such as home, work, and neighbour.

You can use a customer address with an [implicit access token](/docs/api/authentication/create-an-access-token), which is recommended for client-side interactions. You can also use a [client_credentials access token](/docs/api/authentication/create-an-access-token), which is recommended for back-end interactions.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"BearerToken"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Customer Addresses

The API to organize customer addresses.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Delete a Customer Address

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Customer Address"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/customers/{customerID}/addresses/{addressID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete an address for a Customer.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"customerID","in":"path","description":"The ID of the customer that contains the address to delete.","required":true,"schema":{"type":"string"}},{"name":"addressID","in":"path","description":"The ID of the address to delete.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"customer not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Customer Address

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Customer Address"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/customers/{customerID}/addresses/{addressID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get an address for a Customer.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"customerID","in":"path","description":"The ID of the customer you want to retrieve.","required":true,"schema":{"type":"string"}},{"name":"addressID","in":"path","description":"The ID of the address you want to retrieve.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the the type of object. Set this value to `address`.","default":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"customer"}}}}}}}],"title":"CustomerAddressResponse","type":"object"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"customer not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Customer Addresses

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer Addresses"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/customers/{customerID}/addresses"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all addresses for a Customer.

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

### Filtering

The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) addresses:

| Attribute      | Operators                       | Example                               |
|----------------|---------------------------------|---------------------------------------|
| `name`         | `eq`,`in`,`like`,`ilike`,`text` | `ilike(name,"*home*")`                |
| `first_name`   | `eq`,`in`,`like`,`ilike`,`text` | `ilike(first_name,"Ron*")`            |
| `last_name`    | `eq`,`in`,`like`,`ilike`,`text` | `ilike(last_name,"*swan*")`           |
| `phone_number` | `eq`,`in`,`like`,`ilike`,`text` | `ilike(phone_number,"*555*")`         |
| `company_name` | `eq`,`in`,`like`,`ilike`,`text` | `ilike(company_name,"*enterprises*")` |
| `instructions` | `eq`,`in`,`like`,`ilike`,`text` | `text(instructions,"behind bin")`     |
| `line_1`       | `eq`,`in`,`like`,`ilike`,`text` | `ilike(line_1,"*Sunny Street*")`      |
| `line_2`       | `eq`,`in`,`like`,`ilike`,`text` | `ilike(line_2,"*Unit*")`              |
| `city`         | `eq`,`in`,`like`,`ilike`,`text` | `eq(city,"Sunny Town")`               |
| `county`       | `eq`,`in`,`like`,`ilike`,`text` | `eq(county,"Sunnyville")`             |
| `region`       | `eq`,`in`,`like`,`ilike`,`text` | `eq(region,"California")`             |
| `postcode`     | `eq`,`in`,`like`,`ilike`,`text` | `eq(postcode,"SU33 1YY")`             |
| `country`      | `eq`,`in`,`like`,`ilike`,`text` | `eq(country,"GB")`                    |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"customerID","in":"path","description":"The ID of the customer you want to retrieve.","required":true,"schema":{"type":"string"}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. If not specified, defaults to the `page_length` setting from the Settings API.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"page[total_method]","in":"query","description":"The method used to calculate the total count. `lower_bound` limits expensive count operations, `observed` uses a lightweight +1 fetch strategy that will indicate if there is a next page.","required":false,"schema":{"type":"string","enum":["lower_bound","observed"],"default":"lower_bound"}},{"name":"filter","in":"query","description":"Filter addresses using a simple query language.","required":false,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the the type of object. Set this value to `address`.","default":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"customer"}}}}}}}],"title":"CustomerAddressResponse"}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page.","example":25},"offset":{"type":"integer","description":"The current offset by number of records.","example":0},"current":{"type":"integer","description":"The current page number.","example":1},"total":{"type":"integer","description":"The total number of pages.","example":3}},"title":"PaginationPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results.","example":75},"total_method":{"type":"string","description":"The method used to calculate the total. `exact` means the precise count is known, `lower_bound` means the count is at least this value, `observed` means the count is estimated from observations.","enum":["exact","lower_bound","observed"],"example":"exact"}},"title":"PaginationResults"}},"title":"PaginationMeta"},"links":{"type":"object","properties":{"current":{"type":"string","description":"The URL to the current page.","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=0&page[limit]=25"},"first":{"type":"string","description":"The URL to the first page.","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=0&page[limit]=25"},"last":{"type":["string","null"],"description":"The URL to the last page. May be null if the total is unknown.","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=50&page[limit]=25"},"next":{"type":["string","null"],"description":"The URL to the next page. Null if on the last page.","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses?page[offset]=25&page[limit]=25"},"prev":{"type":["string","null"],"description":"The URL to the previous page. Null if on the first page.","example":null}},"title":"PaginationLinks"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"status":400,"title":"Bad Request","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"customer not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Customer Address

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Customer Address"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/customers/{customerID}/addresses"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create an address for a Customer.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"customerID","in":"path","description":"The ID of the customer you want to create an address for.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the the type of object. Set this value to `address`.","default":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the the type of object. Set this value to `address`.","default":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"customer"}}}}}}}],"title":"CustomerAddressResponse"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the the type of object. Set this value to `address`.","default":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"customer"}}}}}}}],"title":"CustomerAddressResponse"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"status":400,"title":"Bad Request","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"customer not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an Customer Address

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Customer Address"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/customers/{customerID}/addresses/{addressID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update an address for a Customer.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"customerID","in":"path","description":"The ID of the customer you want to create an address for.","required":true,"schema":{"type":"string"}},{"name":"addressID","in":"path","description":"The ID of the customer you want to update.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the the type of object. Set this value to `address`.","default":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the the type of object. Set this value to `address`.","default":"address"},"first_name":{"type":"string","description":"The first name of the recipient on this address.","example":"Ron"},"last_name":{"type":"string","description":"The last name of the recipient on this address.","example":"Swanson"},"name":{"type":"string","description":"The name for the address saved, such as `home`, `work` or `wife’s office`.","example":"Home"},"phone_number":{"type":"string","description":"A phone number for this address.","example":"(555) 555-1234"},"instructions":{"type":"string","description":"Any delivery instructions for this address.","example":"Leave behind bin"},"company_name":{"type":"string","description":"The company name at this address.","example":"Ron Swanson Enterprises"},"line_1":{"type":"string","description":"The first portion of the address, usually the street address.","example":"1 Sunny Street"},"line_2":{"type":"string","description":"The second portion of the address, usually an apartment or unit number.","example":"Unit 101"},"city":{"type":"string","description":"The city for this address.","example":"Sunny Town"},"county":{"type":"string","description":"The county for this address.","example":"Sunnyville"},"region":{"type":"string","description":"The state, province, territory, etc. for this address.","example":"acc-legal-name"},"postcode":{"type":"string","description":"The ZIP Code, Postcode, or other postal reference string for this delivery address.","example":"SU33 1YY"},"country":{"type":"string","description":"A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard.","example":"GB"}},"title":"Address"},{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for an Address.","example":"5f8da740-6680-463e-b31c-190b2db4bf9d"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The date the address is created.","type":"string","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the address is updated.","type":"string","example":"2021-02-23T09:40:33.882Z"}}}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/customers/deb6b25f-8451-4211-9a22-95610333df23/addresses"}}}}}],"title":"AddressResponse"},{"type":"object","properties":{"relationships":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"description":"The ID of the customer.","type":"string","example":"11afcf9b-971b-4fdb-8e10-f2ecf970718e"},"type":{"description":"The type of object being returned.","type":"string","example":"customer"}}}}}}}],"title":"CustomerAddressResponse","type":"object"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"status":400,"title":"Bad Request","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP response code of the error."},"title":{"type":"string","description":"A brief summary of the error."},"detail":{"type":"string","description":"Optional additional detail about the error."},"source":{"type":"string","description":"Optional field indicating the source of the error."}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"status":404,"title":"Not Found","detail":"customer not found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create Job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Job"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a Job to export orders to a CSV file. Jobs automatically expire one week after creation. You must fetch the exported data before the jobs expire.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"filter":{"type":"string","example":"gt(created_at,2018-09-01):lt(created_at,2018-10-01):eq(payment,refunded)"},"job_type":{"description":"This represents the type of job. For example, `order_export`.","type":"string","example":"order_export"},"type":{"description":"This represents the type of object being returned. Always `job`.","type":"string","example":"job"}}}},"title":"CreateJob"},{"examples":[{"data":{"description":"Extends the default product object","enabled":true,"name":"Products","slug":"products","type":"flow"}}]}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"filter":"gt(created_at,2018-09-01):lt(created_at,2018-10-01):eq(payment,refunded)","job_type":"order_export","type":"job"}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"id":{"description":"A unique ID generated when a job is created","type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"description":"This represents the type of object being returned. Always `job`.","type":"string","example":"job"},"job_type":{"description":"This represents the type of job. For example, `order_export`.","type":"string","example":"order_export"},"status":{"description":"The status of a job.\n- PENDING - Commerce has received the request but is currently busy processing other requests.\n- STARTED - Commerce has started processing the job.\n- SUCCESS - The job has successfully completed.\n- FAILED - The job has failed.","type":"string","example":"failed"},"error":{"description":"A message describing the error that caused a job to fail.","type":"string","example":"No results matched the supplied filter"},"timestamps":{"type":"object","description":"The date and time a job is created/updated.","properties":{"created_at":{"description":"The date and time a job is created.","type":"string","example":"2018-10-04T11:08:49.156490335Z"},"updated_at":{"description":"The date and time a job is updated.","type":"string","example":"2018-10-04T11:08:49.162867081Z"}},"title":"Timestamps"},"links":{"type":"object","description":"Links are used to allow you to move between requests","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/jobs/974c9db4-38da-4dbf-90c2-33eed5f3e77c"}},"title":"Links"},"link":{"type":"object","description":"A link to the exported data.","properties":{"href":{"description":"The publicly available URL for this CSV file that contains the exported data.","type":"string"}},"title":"FileLink"}},"title":"Job"}}}},"examples":{"default":{"value":{"data":[{"id":"974c9db4-38da-4dbf-90c2-33eed5f3e77c","type":"job","job_type":"order_export","status":"failed","error":"No results matched the supplied filter","link":{"href":""},"links":{"self":"https://useast.api.elasticpath.com/v2/jobs/974c9db4-38da-4dbf-90c2-33eed5f3e77c"},"timestamps":{"created_at":"2018-10-04T11:08:49.156490335Z","updated_at":"2018-10-04T11:08:49.162867081Z"}}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":500,"title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Exporter Service API

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/exporter/exporter.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Exporter Service API"}
>
</Heading>

Use the Exporter Service API to export orders to a Comma-Separated Values (CSV) file. When you run the `export order` endpoint, a job is created.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Get a Job File

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Job File"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/jobs/{jobID}/file"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a link to the CSV file that contains your exported order.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"jobID","description":"The unique identifier of the job whose CSC file you want to retrieve.","in":"path","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"A link to the exported data.","properties":{"href":{"description":"The publicly available URL for this CSV file that contains the exported data.","type":"string"}},"title":"FileLink"}}}}}},"404":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse","example":{"title":"Resource Not Found","status":404,"detail":"The resource you are requesting does not exist"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":500,"title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a Job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Job"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/jobs/{jobID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the specified job.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"jobID","description":"The unique identifier of the requested job.","in":"path","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"properties":{"id":{"description":"A unique ID generated when a job is created","type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"description":"This represents the type of object being returned. Always `job`.","type":"string","example":"job"},"job_type":{"description":"This represents the type of job. For example, `order_export`.","type":"string","example":"order_export"},"status":{"description":"The status of a job.\n- PENDING - Commerce has received the request but is currently busy processing other requests.\n- STARTED - Commerce has started processing the job.\n- SUCCESS - The job has successfully completed.\n- FAILED - The job has failed.","type":"string","example":"failed"},"error":{"description":"A message describing the error that caused a job to fail.","type":"string","example":"No results matched the supplied filter"},"timestamps":{"type":"object","description":"The date and time a job is created/updated.","properties":{"created_at":{"description":"The date and time a job is created.","type":"string","example":"2018-10-04T11:08:49.156490335Z"},"updated_at":{"description":"The date and time a job is updated.","type":"string","example":"2018-10-04T11:08:49.162867081Z"}},"title":"Timestamps"},"links":{"type":"object","description":"Links are used to allow you to move between requests","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/jobs/974c9db4-38da-4dbf-90c2-33eed5f3e77c"}},"title":"Links"},"link":{"type":"object","description":"A link to the exported data.","properties":{"href":{"description":"The publicly available URL for this CSV file that contains the exported data.","type":"string"}},"title":"FileLink"}},"title":"Job"}}},"examples":{"default":{"value":{"data":{"id":"974c9db4-38da-4dbf-90c2-33eed5f3e77c","type":"job","job_type":"order_export","status":"failed","error":"No results matched the supplied filter","link":{"href":""},"links":{"self":"https://useast.api.elasticpath.com/v2/jobs/974c9db4-38da-4dbf-90c2-33eed5f3e77c"},"timestamps":{"created_at":"2018-10-04T11:08:49.156490335Z","updated_at":"2018-10-04T11:08:49.162867081Z"}}}}}}}},"404":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse","example":{"title":"Resource Not Found","status":404,"detail":"The resource you are requesting does not exist"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":500,"title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get All Jobs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get All Jobs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can use this endpoint to display the status of your jobs.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"id":{"description":"A unique ID generated when a job is created","type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"description":"This represents the type of object being returned. Always `job`.","type":"string","example":"job"},"job_type":{"description":"This represents the type of job. For example, `order_export`.","type":"string","example":"order_export"},"status":{"description":"The status of a job.\n- PENDING - Commerce has received the request but is currently busy processing other requests.\n- STARTED - Commerce has started processing the job.\n- SUCCESS - The job has successfully completed.\n- FAILED - The job has failed.","type":"string","example":"failed"},"error":{"description":"A message describing the error that caused a job to fail.","type":"string","example":"No results matched the supplied filter"},"timestamps":{"type":"object","description":"The date and time a job is created/updated.","properties":{"created_at":{"description":"The date and time a job is created.","type":"string","example":"2018-10-04T11:08:49.156490335Z"},"updated_at":{"description":"The date and time a job is updated.","type":"string","example":"2018-10-04T11:08:49.162867081Z"}},"title":"Timestamps"},"links":{"type":"object","description":"Links are used to allow you to move between requests","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/jobs/974c9db4-38da-4dbf-90c2-33eed5f3e77c"}},"title":"Links"},"link":{"type":"object","description":"A link to the exported data.","properties":{"href":{"description":"The publicly available URL for this CSV file that contains the exported data.","type":"string"}},"title":"FileLink"}},"title":"Job"}}}},"examples":{"default":{"value":{"data":[{"id":"974c9db4-38da-4dbf-90c2-33eed5f3e77c","type":"job","job_type":"order_export","status":"failed","error":"No results matched the supplied filter","link":{"href":""},"links":{"self":"https://useast.api.elasticpath.com/v2/jobs/974c9db4-38da-4dbf-90c2-33eed5f3e77c"},"timestamps":{"created_at":"2018-10-04T11:08:49.156490335Z","updated_at":"2018-10-04T11:08:49.162867081Z"}}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":500,"title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Jobs

Jobs have the following characteristics:

  - Jobs are asynchronous.
  - This process is repeated until all jobs are processed.
  - Jobs have a different status, depending on where a job is in its lifecycle.
  - Jobs are processed one at a time. You can continue to send requests using endpoints that function as jobs, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date.
  - Jobs include the data used when an endpoint is run.
  - Jobs report messages and/or errors to help you understand the reasons for any failed jobs.
    
### Job Lifecycle
    
A job can have the following status:

- PENDING - Commerce has received the request but is currently busy processing other requests.
- STARTED - Commerce has started processing the job.
- SUCCESS - The job has successfully completed.
- FAILED - The job has failed.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Create a Field

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Field"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint creates a field.
- For Product Experience Manager, this endpoint creates an attribute.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"allOf":[{"title":"FieldRequest","type":"object","required":["data"],"properties":{"data":{"type":"object","required":["required","type","field_type","slug","name","description"],"properties":{"default":{"type":"number","description":"Specifies a default value for a field/attribute if no value is provided and the field/attribute is required.","examples":[0]},"description":{"type":"string","description":"A description for a field/attribute.","examples":["Average rating as given by our users"]},"enabled":{"type":"boolean","examples":[true]},"field_type":{"type":"string","description":"This field is immutable and cannot be updated. You can have the following field types: \n - `string`\n - `integer`\n - `boolean`\n - `float`\n - `date`\n - `relationship`\n","examples":["integer"]},"name":{"type":"string","description":"The name of a field/attribute.","examples":["Product Rating"]},"order":{"type":"number","description":"Denotes the order in which a field/attribute is returned relative to the rest of flow fields/template attributes.","examples":[1]},"relationships":{"type":"object","description":"Relationships are established between different flow/template entities. For example, a field/attribute is related to a flow/template, as the field/attribute is attached to the flow/template.","required":["flow"],"properties":{"flow":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"flow"}}}}}},"title":"FieldRelationships"},"required":{"type":"boolean","description":"`true` if required on input, `false` if not. Always `false` if the `field_type` `relationship`.\n","examples":[false]},"slug":{"type":"string","description":"A unique identifier of a field/attribute.","examples":["product-rating"]},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["field"]},"validation_rules":{"type":"array","items":{"type":"object","description":"An array of validation rule objects. See [Field/attribute Validation Rules](#fieldattribute-validation-rules).","properties":{"type":{"type":"string","description":"The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.","example":"enum","enum":["enum","email","slug","between","one-to-many","one-to-one"]},"options":{"anyOf":[{"type":"array","description":"An array of valid string values.","items":{"type":"string"}},{"type":"object","description":"An object containing `from` and `to` numbers.","properties":{"from":{"type":["number","string"],"example":1},"to":{"type":["number","string"],"example":5}}}]},"to":{"type":"string","example":"customer"}},"title":"FieldValidationRules"},"description":"An array of validation rule objects. See [**Field Validation Rules**](#fieldattribute-validation-rules).","examples":[{"options":{"from":1,"to":5},"type":"between"}]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"default":4,"description":"Average rating as given by our users","enabled":true,"field_type":"integer","name":"Product Rating","order":1,"relationships":{"flow":{"data":{"id":"{{flowID}}","type":"flow"}}},"required":false,"slug":"product-rating","type":"field","validation_rules":[{"options":{"from":1,"to":5},"type":"between"}]}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Field","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["field"]},"field_type":{"type":"string","description":"This field is immutable and cannot be updated. You can have the following field types:\n- `string`\n- `integer`\n- `boolean`\n- `float`\n- `date`\n- `relationship`\n","examples":["integer"]},"slug":{"type":"string","description":"A short description for a field/attribute.","examples":["product-rating"]},"name":{"type":"string","description":"The name of a field/attribute.","examples":["Product Rating"]},"description":{"type":"string","description":"A short description of a field/attribute.","examples":["Average rating as given by our users"]},"required":{"type":"boolean","description":"`true` if required on input, `false` if not. Always `false` if the `field_type` is a relationship.\n","examples":[true]},"default":{"type":["boolean","number","string","null"],"description":"A default value if none is supplied and a field/attribute is not required.","examples":[1]},"enabled":{"type":"boolean","examples":[true]},"order":{"type":["number","null"],"description":"Denotes the order in which this field is returned relative to the rest of the flow/template fields/attributes.","examples":[1]},"omit_null":{"type":"boolean","description":"Hide this field/attribute from responses if the value is `null`.","examples":[true]},"validation_rules":{"type":"array","items":{"type":"object","description":"An array of validation rule objects. See [Field/attribute Validation Rules](#fieldattribute-validation-rules).","properties":{"type":{"type":"string","description":"The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.","example":"enum","enum":["enum","email","slug","between","one-to-many","one-to-one"]},"options":{"anyOf":[{"type":"array","description":"An array of valid string values.","items":{"type":"string"}},{"type":"object","description":"An object containing `from` and `to` numbers.","properties":{"from":{"type":["number","string"],"example":1},"to":{"type":["number","string"],"example":5}}}]},"to":{"type":"string","example":"customer"}},"title":"FieldValidationRules"}},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"links":{"type":"object","description":"Links allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Listing pages use the following:\n\n| Property | Description |\n| --- | --- |\n| `current` | Always the current page |\n| `first` | Always the first page |\n| `last` | `null` if there is only one page. |\n| `previous` | `null` if you are on the first page. |\n| `next` | `null` if there is only one page. |\n","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/3cf3ad3f-b12c-4a08-a6ab-05e6aab0122c/fields/c1c788d1-f1c7-4b90-938f-f158f3353c66"}},"title":"FieldLinks"},"relationships":{"type":"object","description":"Relationships are established between different flow/template entities. For example, a field/attribute is related to a flow/template, as the field/attribute is attached to the flow/template.","required":["flow"],"properties":{"flow":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"flow"}}}}}},"title":"FieldRelationships"}}}}},"examples":{"default":{"value":{"data":{"type":"field","name":"Product Rating","slug":"product-rating","field_type":"integer","validation_rules":[{"type":"between","options":{"from":1,"to":5}}],"description":"Average rating as given by our users","required":false,"default":0,"enabled":true,"order":1,"omit_null":false,"relationships":{"flow":{"data":{"type":"flow","id":"e4145c27-aba1-46af-81a3-58f5e1cf7f15"}}}}}}}}}},"403":{"description":"Forbidden. The request was valid but the token does not have permission to perform this operation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"forbidden":{"value":{"errors":[{"title":"Forbidden","status":"403"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Flow

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Flow"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/flows"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint creates a flow.
- For Product Experience Manager, this endpoint creates a template.

:::caution

Custom names and values prefixed with $ are not supported.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"allOf":[{"title":"FlowsRequest","type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","name","slug","enabled","description"],"properties":{"description":{"type":"string","description":"A brief description of a flow/template outlining details such as purpose, usage instructions and so on.","examples":["A flow to extend the `customer` resource.","A SizeGuide template for the clothing that we sell."]},"enabled":{"type":"boolean","examples":[true]},"name":{"type":"string","description":"The name of a flow/template.","examples":["Products"]},"slug":{"type":"string","description":"A unique slug identifier for a flow/template.","examples":["products"]},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["flow"]}}}}},{"examples":[{"data":{"description":"Extends the default product object","enabled":true,"name":"Products","slug":"products","type":"flow"}}]}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"description":"Extends the default product object","enabled":true,"name":"Products","slug":"products","type":"flow"}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Flows","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"A unique identifier for a flow/template.","example":"flow"},"name":{"type":"string","description":"The name of a flow/template.","example":"Products"},"slug":{"type":"string","description":"A unique identifier of a flow/template.","example":"products"},"description":{"type":"string","description":"A short description for a flow/template.","example":"Extends the default product object"},"enabled":{"type":"boolean","example":true},"links":{"type":"object","description":"Link to the current resource.","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84"}},"title":"SelfLink"},"relationships":{"type":"object","description":"Relationships are established between different flows/templates entities. For example, a field and an entry are related to a flow as both are attached to it.","properties":{"fields":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Relationships","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"brand"}}}}}}},"title":"FlowsRelationships"},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"}}}}},"examples":{"default":{"value":{"data":{"id":"6d320b42-237d-4474-8452-d49f884d4ae1","type":"flow","name":"Products-1","slug":"products-1","description":"Extends the default product object","enabled":true,"links":{"self":"https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1"},"relationships":{},"meta":{"owner":"organization","timestamps":{"created_at":"2018-05-10T18:04:26.623Z","updated_at":"2018-05-10T18:04:26.623Z"}}}}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create an Entry Relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Entry Relationship"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/flows/{flowSlug}/entries/{flowEntryID}/relationships/{flowFieldSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- In Commerce, create an entry relationship to one or more resources. If any relationships already exist, the ones made in the request are added to them.
- In Product Experience Manager, create an entry relationship with the product to which you want to associate the template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug of the flow/template that the entry belongs to.","style":"simple","schema":{"type":"string"}},{"name":"flowFieldSlug","in":"path","required":true,"description":"The slug of the field/attribute that the relationship belongs to.","style":"simple","schema":{"type":"string"}},{"name":"flowEntryID","in":"path","required":true,"description":"The ID of the entry you are requesting.","style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"allOf":[{"title":"FlowsEntriesRelationshipsFieldSlugRequest","type":"object","properties":{"data":{"type":"array","description":"The data to be stored.","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"The resource type of the object.","examples":["customer"]}}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":[{"id":"{RESOURCE_ID}","type":"{RESOURCE_TYPE}"},{"id":"{RESOURCE_ID}","type":"{RESOURCE_TYPE}"}]}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Relationships","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"brand"}}}}}},"examples":{"default":{"value":{"data":[{"type":"brand","id":"0d28e5b6-f615-4e1c-b038-275cfde97927"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create an Entry

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Entry"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/flows/{flowSlug}/entries"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint creates an entry for a flow.
- For Product Experience Manager, this endpoint creates an entry for a template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug for the flow/template you want to create an entry for.","style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"allOf":[{"title":"FlowsEntriesRequest","type":"object","properties":{"data":{"type":"object","description":"Specifies the type of the resource object.","properties":{"FIELD_SLUG":{"type":"string","description":"Where **FIELD_SLUG** is the slug for each field/attribute on this flow/template along with the corresponding value. You must provide a field slug and a value for the entry. You can have multiple field slugs if they are related to the flow/template.","examples":["a value"]},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["entry"]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"FIELD_SLUG":"a value","type":"entry"}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Entry","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"entry"},"links":{"type":"object","description":"Link to the current resource.","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84"}},"title":"SelfLink"},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"relationships":{"type":"object","additionalProperties":true,"description":"Dynamic relationship fields keyed by field slug."}},"additionalProperties":{"description":"There can be a `:fieldSlug` attribute for each field/attribute attached to a flow/template. The type depends on the field type."}}}},"examples":{"default":{"value":{"data":{"id":"10fe2aca-09fb-42fe-a1d4-081134320641","type":"entry","meta":{"owner":"organization","timestamps":{"created_at":"2021-10-26T17:10:56.329Z","updated_at":"2021-10-26T17:10:56.329Z"}},"links":{"self":"https://epcc-integration.global.ssl.fastly.net/v2/flows/products/entries/10fe2aca-09fb-42fe-a1d4-081134320641"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Conflict. The request could not be completed due to a conflict with the current state of the resource.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict":{"value":{"errors":[{"title":"Conflict","status":"409"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a Field

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Field"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/fields/{flowFieldID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint deletes a field.
- For Product Experience Manager, this endpoint deletes an attribute.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowFieldID","description":"The unique identifier of the field/attribute that you want to delete.","in":"path","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden. The request was valid but the token does not have permission to perform this operation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"forbidden":{"value":{"errors":[{"title":"Forbidden","status":"403"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a Flow

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Flow"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/flows/{flowID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint deletes a flow. We recommend that you remove all the fields assigned to a flow before deleting a flow.
- For Product Experience Manager, this endpoint deletes a template. We recommend that you remove all the attributes assigned to a template before deleting a template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowID","description":"The unique identifier of the flow/template you want to delete.","in":"path","required":true,"style":"simple","schema":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden. The request was valid but the token does not have permission to perform this operation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"forbidden":{"value":{"errors":[{"title":"Forbidden","status":"403"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete an Entry Relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an Entry Relationship"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/flows/{flowSlug}/entries/{flowEntryID}/relationships/{flowFieldSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- In Commerce, deletes an entry relationship to one or more resources. 
- In Product Experience Manager, deletes an entry relationship with the product to which you want to associate the template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug of the flow/template that the entry belongs to.","style":"simple","schema":{"type":"string"}},{"name":"flowFieldSlug","in":"path","required":true,"description":"The slug of the field/attribute that the relationship belongs to.","style":"simple","schema":{"type":"string"}},{"name":"flowEntryID","in":"path","required":true,"description":"The ID of the entry you are requesting.","style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete an Entry

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an Entry"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/flows/{flowSlug}/entries/{flowEntryID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint deletes an entry from a flow.
- For Product Experience Manager, this endpoint deletes an entry from a template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug for the flow/template.","style":"simple","schema":{"type":"string"}},{"name":"flowEntryID","in":"path","required":true,"description":"The ID of the entry.","style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden. The request was valid but the token does not have permission to perform this operation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"forbidden":{"value":{"errors":[{"title":"Forbidden","status":"403"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Entries

### Entries in Commerce

Entries hold the pieces of data collected within the fields. If your flow has more than one field related to it, you see multiple field slugs.

### Entries in Product Experience Manager

Entries hold the pieces of data collected within the attributes. If your template has more than one attribute related to it, you see multiple attribute slugs.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Entry Relationships

### Entry Relationships in Commerce

When you create a field that uses `relationship` as a `field_type`, you update your entry values using the `Entry Relationship` endpoints. 

### Entry Relationships in Product Experience Manager

Once you have created your templates, you must associate them with your products using the `Entry Relationship` endpoints.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Fields

With fields, you can:

- in Commerce, use a field in your flows to represent  single field of data (for example a `Product Rating`) to be applied to an entity
- in Product Experience Manager, use an attribute in your template to attach a characteristic like `color` to a product.

A field/attribute represents a single piece of data. All fields/attributes have a `field_type` (`string`, `integer`, `boolean`, `date` or `relationship`), a default value, and an optional set of validation rules.

:::caution

- Custom names and values prefixed with `$` are not supported.
- There is a hard limit of 100 fields per flow.
- You can configure default values for fields. If you choose to do so, you must ensure that your default field values comply with your validation rules.

:::

#### Field/Attribute Validation Rules

When creating a field/attribute, you can add validation to the values that are stored. The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.

#### `string` / `enum`

Must be one of a predefined collection of strings. If you leave the field blank or enter an incorrect value then an `Invalid Value` error is displayed. 

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `enum` |
| `options` | `array[string]` | An array of valid string values. |

##### `string` / `email`

Must be a valid email address.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `email` |

##### `string` / `slug`

Can contain only letters, numbers, hyphens and underscores.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `slug` |

##### `integer` / `between`

Must be between the two provided values.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `enum` |
| `options` | `object` | An object containing `from` and `to` integers. |

##### `integer` / `enum`

Must be one of a predefined collection of integers.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `enum` |
| `options` | `array[integer]` | An array of valid integer values. |

##### `float` / `between`

Must be between the two provided values.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `enum` |
| `options` | `object` | An object containing `from` and `to` floats. |

##### `float` / `enum`

Must be one of a predefined collection of floats.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `enum` |
| `options` | `array[float]` | An array of valid float values. |

#### `date` / `enum`

Must be one of a predefined collection of dates.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `enum` |
| `options` | `array[string]` | An array of valid date values as strings \(`YYYY-MM-DD HH:MM:SS` - time is optional\). |

##### `relationship` / `one-to-many`

:::caution
This only applies to Commerce. You cannot use relationships in Product Experience Manager templates.
:::

Allows multiple relationships to be created.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `one-to-many` |
| `to` | `string` | The entity type you are making relationships with in singular form (for example, `product`). |

##### `relationship` / `one-to-one`

:::caution
This only applies to Commerce. You cannot use relationships in Product Experience Manager templates.
:::

Allows only a single relationships to be created on an entry.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `type` | `string` | `one-to-one` |
| `to` | `string` | The entity type you are making relationships with in singular form (for example, `customer`). |

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Flows Service Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/flows/flows.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Flows Service Introduction"}
>
</Heading>

With flows you can extend the capabilities of Commerce and Product Experience Manager at both organization and store level, and apply Composable Commerce to almost any use case.
 
### Flows in Commerce
 
You can define custom data fields for the resources that you use in your store or organization, such as adding more fields to the `customer` resource. 
 
 You can also create new resources, such as a `wishlist` resource to support wishlists in your store. 
 
:::note
 
 [Custom APIs](/docs/api/commerce-extensions/custom-ap-is#custom-apis-vs-non-core-flows) are the next generation of Non-Core Flows. Flows are not going anywhere, but Custom APIs offer enhanced capabilities. We recommend using Custom APIs for any of your new use cases.
 
:::

:::caution
 
- In an organization, not all resources are available. See [**Extend a resource**](https://elasticpath.dev/guides/Custom%20Data/extend-any-resource) for a list of organization resources that can be extended.
- If you store any sensitive Personal Identifiable Information (PII) or non-public data on your site, ensure that you do not use this data in flows to avoid potential unauthorized access to the data. For more information, see [**Permissions**](/docs/authentication/tokens/permissions).
 
:::
 
### Templates in Product Experience Manager
 
 Templates allow you to attach a specific set of attributes to your products.
 
 - You can use templates to define characteristics of your product, for example, a product specification. For example, a *Book* template might contain attributes, such as *ISBN*, *Author*, *Number of pages*, *Year Published*, or *Condition (New/Used)*.
 - You can use templates for Search Engine Optimization (SEO). When you assign template attributes such as, *care instructions* or *fabric*, to a shirt and a shopper searches for a specific item, attributes help stores to return the products that match the search criteria. For example, when a shopper searches for a large blue shirt, all shirts that are large and blue are returned in the search result.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Flows

### Flows in Commerce

There are two scenarios for using flows:

- Extend an existing resource, such as customers and orders.
- Create a new resource, such as a blog, wishlist, or customer review.

#### Extend an existing resource

The most common usage of the Flows API is to extend existing resources, such as `customers` and `orders`. These types of resources are called core flows and are handled differently than non-core flows. See [**Core and non-core flows**](#core-and-non-core-flows).

For example, you can extend the `customer` resource to store custom data, such as a `user_profile` field for customers. Or you might want to add an `age` field to store a customer's age.

Extending a resource applies only to core flows. When creating a new flow, make sure the `slug` matches that of a core resource listed in the following table.

| Flow slug                                   | Description                    | Availability Level |
|:--------------------------------------------|:-------------------------------| :---|
| `accounts`                                  | Extend the [`account`](/docs/api/accounts/account-management-introduction) object. | Store |
| `account-members`                           | Extend the [`account-members`](/docs/api/accounts/account-members) object. | Store |
| `account-memberships`                       | Extend the [`account-membership`](/docs/api/accounts/account-membership) object. | Store |
| `addresses`                                 | Extend the [`address`](/docs/api/addresses/account-addresses) object. | Store |
| `authentication-realms`                     | Extend the [`authentication-realms`](/docs/api/single-sign-on/authentication-realms) object. | Store |
| `carts`                                     | Extend the [`carts`](/docs/api/carts/carts-checkout-orders-introduction) object. | Organization/Store |
| `cart_items`                                | Extend the [`cart_item`](/docs/api/carts/cart-items) object. | Organization/Store |
| `customers`                                 | Extend the [`customer`](/docs/customer-management/customer-management-api/customer-management-api-overview) object. **Note**: Please use Account Management for all new frontend experiences.  | n/a |
| `oidc-profiles`                             | Extend the [`oidc-profiles`](/docs/api/single-sign-on/oidc-profiles) object. | Store |
| `order_items`                               | Extend the [`order_item`](/docs/api/carts/get-order-items) object. | Organization/Store |
| `orders`                                    | Extend the [`order`](/docs/api/carts/orders) object. | Organization/Store |
| `password-profiles`                         | Extend the [`password-profiles`](/docs/api/single-sign-on/password-profiles) object. | Store |
| `products`                                  | Extend the [`product`](/docs/api/pxm/products/products) object. | Store |
| `promotions`                                | Extend the [`promotion`](/docs/api/promotions/promotions-standard-introduction) object. | Store |
| `rule-promotions`                           | Extend the [`rule-promotion`](/docs/api/promotions-builder/create-rule-promotion) object. | Store |
| `user-authentication-info`                  | Extend the [`user-authentication-info`](/docs/api/single-sign-on/user-authentication-infos) object. | Store |
| `user-authentication-oidc-profile-info`     | Extend the [`user-authentication-oidc-profile-info`](/docs/api/single-sign-on/user-authentication-oidc-profile-infos) object. | Store |
| `user-authentication-password-profile-info` | Extend the [`user-authentication-password-profile-info`](/docs/api/single-sign-on/user-authentication-password-profile-infos) object. | Store |
| `catalogs`                                  | Extend the [`catalog`](/docs/api/pxm/catalog/catalogs) object. It will not extend the [`catalog-release`](/docs/api/pxm/catalog/releases) object. | Store |
| `shipping-groups`                           | Extend the [`shipping-group`](/docs/api/carts/create-shipping-group) object. | Store |

#### Create a new resource

You can create new resources to support product reviews, wish lists, blog articles, staff profile pages, and many more. These non-core flows are referred to as custom flows. See [**Core and non-core flows**](#core-and-non-core-flows).

:::note

[Custom APIs](/docs/api/commerce-extensions/custom-ap-is#custom-apis-vs-non-core-flows) are the next generation of Non-Core Flows. Flows are not going anywhere, but Custom APIs offer enhanced capabilities. We recommend using Custom APIs for any of your new use cases.

:::

#### Core and non-core flows

The following table describes the differences between core and non-core flows:

| Core Flows                                                    | Non-core Flows |
|:--------------------------------------------------------------|:-------------|
| Extend an existing resource.                                  | Create a new resource. |
| Entries managed automatically by Commerce. | Create and manage entries manually. |
| Requests are sent to the `fields` endpoint.                   | Requests are sent to the `entries` endpoint. |

:::caution

You cannot delete core flows after creating them with the API or Commerce Manager.

:::

#### Flows taxonomy

Fields and entries are an integral part of flows. A flow describes a collection of fields. A field represents a single field of data. An entry is a specific instance of a flow, and is associated with a specific instance of an entity, such as a single customer. Entries for core flows (existing resources) are managed automatically for you.

In database terms, you can think of flows as tables, fields as columns, and entries as database records.

### Templates in Product Experience Manager

Templates allow you to attach a specific set of attributes to your products.

- You can use templates to define characteristics of your products.
- You can use templates for Search Engine Optimization (SEO).

#### Template Taxonomy

Attributes and entries are integral to templates. A template describes a collection of attributes. An attribute represents a single characteristic, like color. An entry is a specific instance of an attribute, for example, blue, and is associated with a specific product.

  A template is exactly the same as a flow except it has a different naming convention. The name of a template is in the format **products(*slug*)** where *slug* is the slug of a template.

#### Associating templates with products

  Once you have created your template, and [**associated**](/docs/api/flows/create-an-entry-relationship) the temp with a product in Product Experience Manager, it becomes a template. 

  For example, if you create a template with a slug of `SizeGuide` then the template name is **products(SizeGuide)**. You can then [**associate**](/docs/api/flows/create-an-entry-relationship) this template to all clothing products in your store and the slug is included in all the responses that contain products.

   You can create product templates for both organization and store. In addition, stores can use organization templates for store-level products.

  For more information about adding attributes, see [**Fields**](/docs/api/flows/fields).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Get a Field

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Field"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/fields/{flowFieldID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint retrieves a field.
- For Product Experience Manager, this endpoint retrieves an attribute.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowFieldID","description":"The unique identifier of the flow/template whose field/attribute you want to retrieve.","in":"path","required":true,"style":"simple","schema":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Field","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["field"]},"field_type":{"type":"string","description":"This field is immutable and cannot be updated. You can have the following field types:\n- `string`\n- `integer`\n- `boolean`\n- `float`\n- `date`\n- `relationship`\n","examples":["integer"]},"slug":{"type":"string","description":"A short description for a field/attribute.","examples":["product-rating"]},"name":{"type":"string","description":"The name of a field/attribute.","examples":["Product Rating"]},"description":{"type":"string","description":"A short description of a field/attribute.","examples":["Average rating as given by our users"]},"required":{"type":"boolean","description":"`true` if required on input, `false` if not. Always `false` if the `field_type` is a relationship.\n","examples":[true]},"default":{"type":["boolean","number","string","null"],"description":"A default value if none is supplied and a field/attribute is not required.","examples":[1]},"enabled":{"type":"boolean","examples":[true]},"order":{"type":["number","null"],"description":"Denotes the order in which this field is returned relative to the rest of the flow/template fields/attributes.","examples":[1]},"omit_null":{"type":"boolean","description":"Hide this field/attribute from responses if the value is `null`.","examples":[true]},"validation_rules":{"type":"array","items":{"type":"object","description":"An array of validation rule objects. See [Field/attribute Validation Rules](#fieldattribute-validation-rules).","properties":{"type":{"type":"string","description":"The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.","example":"enum","enum":["enum","email","slug","between","one-to-many","one-to-one"]},"options":{"anyOf":[{"type":"array","description":"An array of valid string values.","items":{"type":"string"}},{"type":"object","description":"An object containing `from` and `to` numbers.","properties":{"from":{"type":["number","string"],"example":1},"to":{"type":["number","string"],"example":5}}}]},"to":{"type":"string","example":"customer"}},"title":"FieldValidationRules"}},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"links":{"type":"object","description":"Links allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Listing pages use the following:\n\n| Property | Description |\n| --- | --- |\n| `current` | Always the current page |\n| `first` | Always the first page |\n| `last` | `null` if there is only one page. |\n| `previous` | `null` if you are on the first page. |\n| `next` | `null` if there is only one page. |\n","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/3cf3ad3f-b12c-4a08-a6ab-05e6aab0122c/fields/c1c788d1-f1c7-4b90-938f-f158f3353c66"}},"title":"FieldLinks"},"relationships":{"type":"object","description":"Relationships are established between different flow/template entities. For example, a field/attribute is related to a flow/template, as the field/attribute is attached to the flow/template.","required":["flow"],"properties":{"flow":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"flow"}}}}}},"title":"FieldRelationships"}}}}},"examples":{"default":{"value":{"data":{"id":"102b2087-d56a-45e7-bf1c-e9517716abb3","type":"field","field_type":"integer","slug":"product-rating","name":"Product Rating","description":"Average rating as given by our users","required":false,"default":null,"enabled":true,"validation_rules":[{"type":"between","options":{"from":1,"to":5}}],"order":1,"omit_null":false,"links":{"self":"https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1/fields/102b2087-d56a-45e7-bf1c-e9517716abb3"},"relationships":{"flow":{"data":{"id":"6d320b42-237d-4474-8452-d49f884d4ae1","type":"flow"}}},"meta":{"owner":"organization","timestamps":{"created_at":"2018-05-10T18:19:11.559Z","updated_at":"2018-05-10T18:19:11.559Z"}}}}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a Flow

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Flow"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/flows/{flowID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint retrieves a flow.
- For Product Experience Manager, this endpoint retrieves a template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowID","description":"The unique identifier of the flow/template you want to retrieve.","in":"path","required":true,"style":"simple","schema":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Flows","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"A unique identifier for a flow/template.","example":"flow"},"name":{"type":"string","description":"The name of a flow/template.","example":"Products"},"slug":{"type":"string","description":"A unique identifier of a flow/template.","example":"products"},"description":{"type":"string","description":"A short description for a flow/template.","example":"Extends the default product object"},"enabled":{"type":"boolean","example":true},"links":{"type":"object","description":"Link to the current resource.","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84"}},"title":"SelfLink"},"relationships":{"type":"object","description":"Relationships are established between different flows/templates entities. For example, a field and an entry are related to a flow as both are attached to it.","properties":{"fields":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Relationships","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"brand"}}}}}}},"title":"FlowsRelationships"},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"}}}}},"examples":{"default":{"value":{"data":{"id":"38ba1451-efa4-4361-9ca6-3fb646490f37","type":"flow","name":"extraFieldRenamed","slug":"products","description":"Extends the default product object","enabled":true,"links":{"self":"https://useast.api.elasticpath.com/v2/flows/38ba1451-efa4-4361-9ca6-3fb646490f37"},"relationships":{},"meta":{"owner":"organization","timestamps":{"created_at":"2018-05-10T01:41:36.009Z","updated_at":"2018-05-10T15:27:26.241Z"}}}}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Entries

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Entries"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/flows/{flowSlug}/entries"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint retrieves all entries for a flow.
- For Product Experience Manager, this endpoint retrieves all entries for a template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug for the flow/template you want to create an entry for.","style":"simple","schema":{"type":"string"}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.\n","in":"query","style":"form","explode":true,"schema":{"type":"string","examples":["10"]}},{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.\n","in":"query","style":"form","explode":true,"schema":{"type":"string","examples":["0"]}},{"name":"filter","in":"query","required":false,"description":"Filter resources using the filter query parameter. See [**Filtering**](/guides/Getting-Started/filtering).","schema":{"type":"string","example":"eq(owner,organization)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Entry","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"entry"},"links":{"type":"object","description":"Link to the current resource.","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84"}},"title":"SelfLink"},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"relationships":{"type":"object","additionalProperties":true,"description":"Dynamic relationship fields keyed by field slug."}},"additionalProperties":{"description":"There can be a `:fieldSlug` attribute for each field/attribute attached to a flow/template. The type depends on the field type."}}},"links":{"type":"object","description":"Pagination links returned on list responses.\n\n| Property | Description |\n| --- | --- |\n| `current` | Always the current page |\n| `first` | Always the first page |\n| `last` | `null` if there is only one page. |\n| `previous` | `null` if you are on the first page. |\n| `next` | `null` if there is only one page. |\n","properties":{"current":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows?page[offset]=0&page[limit]=100"},"first":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows?page[offset]=0&page[limit]=100"},"last":{"type":["string","null"],"example":"https://euwest.api.elasticpath.com/v2/flows?page[offset]=0&page[limit]=100"},"next":{"type":["string","null"],"example":null},"previous":{"type":["string","null"],"example":null}},"title":"ListLinks"},"meta":{"type":"object","description":"Pagination metadata returned on list responses.","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The number of items per page.","example":100},"offset":{"type":"integer","description":"The current pagination offset.","example":0},"current":{"type":"integer","description":"The current page number.","example":1},"total":{"type":"integer","description":"The total number of pages.","example":1}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results across all pages.","example":5}}}},"title":"PageMeta"}}},"examples":{"default":{"value":{"data":[{"id":"ce1f0b19-23c3-487b-aa2a-552b77abdf0c","type":"entry","brand-image":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/61118f21-14a2-466c-a84b-c30b1f900cf9.png","meta":{"owner":"organization","timestamps":{"created_at":"2018-06-05T20:58:25.596Z","updated_at":"2018-06-05T20:58:25.596Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/flows/brands/entries/ce1f0b19-23c3-487b-aa2a-552b77abdf0c"}},{"id":"a5fcf6bc-233f-44d7-a3b0-0961eed3df9d","type":"entry","brand-image":"some image for brand x","meta":{"owner":"organization","timestamps":{"created_at":"2018-06-06T14:48:59.006Z","updated_at":"2018-06-06T14:48:59.006Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/flows/brands/entries/a5fcf6bc-233f-44d7-a3b0-0961eed3df9d"}}],"links":{"current":"https://useast.api.elasticpath.com/v2/flows/brands/entries?page[limit]=20&page[offset]=0","first":"https://useast.api.elasticpath.com/v2/flows/brands/entries?page[limit]=20&page[offset]=0","last":null,"next":null,"previous":null},"meta":{"page":{"limit":20,"offset":0,"current":1,"total":1},"results":{"total":2}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Fields by Flow

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Fields by Flow"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/flows/{flowSlug}/fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all Fields by Flow

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug of the flow the entry belongs to.","style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Field","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["field"]},"field_type":{"type":"string","description":"This field is immutable and cannot be updated. You can have the following field types:\n- `string`\n- `integer`\n- `boolean`\n- `float`\n- `date`\n- `relationship`\n","examples":["integer"]},"slug":{"type":"string","description":"A short description for a field/attribute.","examples":["product-rating"]},"name":{"type":"string","description":"The name of a field/attribute.","examples":["Product Rating"]},"description":{"type":"string","description":"A short description of a field/attribute.","examples":["Average rating as given by our users"]},"required":{"type":"boolean","description":"`true` if required on input, `false` if not. Always `false` if the `field_type` is a relationship.\n","examples":[true]},"default":{"type":["boolean","number","string","null"],"description":"A default value if none is supplied and a field/attribute is not required.","examples":[1]},"enabled":{"type":"boolean","examples":[true]},"order":{"type":["number","null"],"description":"Denotes the order in which this field is returned relative to the rest of the flow/template fields/attributes.","examples":[1]},"omit_null":{"type":"boolean","description":"Hide this field/attribute from responses if the value is `null`.","examples":[true]},"validation_rules":{"type":"array","items":{"type":"object","description":"An array of validation rule objects. See [Field/attribute Validation Rules](#fieldattribute-validation-rules).","properties":{"type":{"type":"string","description":"The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.","example":"enum","enum":["enum","email","slug","between","one-to-many","one-to-one"]},"options":{"anyOf":[{"type":"array","description":"An array of valid string values.","items":{"type":"string"}},{"type":"object","description":"An object containing `from` and `to` numbers.","properties":{"from":{"type":["number","string"],"example":1},"to":{"type":["number","string"],"example":5}}}]},"to":{"type":"string","example":"customer"}},"title":"FieldValidationRules"}},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"links":{"type":"object","description":"Links allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Listing pages use the following:\n\n| Property | Description |\n| --- | --- |\n| `current` | Always the current page |\n| `first` | Always the first page |\n| `last` | `null` if there is only one page. |\n| `previous` | `null` if you are on the first page. |\n| `next` | `null` if there is only one page. |\n","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/3cf3ad3f-b12c-4a08-a6ab-05e6aab0122c/fields/c1c788d1-f1c7-4b90-938f-f158f3353c66"}},"title":"FieldLinks"},"relationships":{"type":"object","description":"Relationships are established between different flow/template entities. For example, a field/attribute is related to a flow/template, as the field/attribute is attached to the flow/template.","required":["flow"],"properties":{"flow":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"flow"}}}}}},"title":"FieldRelationships"}}}}}},"examples":{"default":{"value":{"data":[{"id":"23d26fd2-d2e2-4c72-b4b4-3ef7a31bc47f","type":"field","field_type":"string","slug":"background_color","name":"background colors","description":"background color for the product","required":false,"default":"#ffffff","enabled":true,"validation_rules":[],"order":null,"omit_null":false,"links":{"self":"https://useast.api.elasticpath.com/v2/flows/248c7776-bd9f-4075-8980-461b02ed3757/fields/23d26fd2-d2e2-4c72-b4b4-3ef7a31bc47f"},"relationships":{"flow":{"data":{"id":"248c7776-bd9f-4075-8980-461b02ed3757","type":"flow"}}},"meta":{"owner":"organization","timestamps":{"created_at":"2017-06-26T12:55:33.560Z","updated_at":"2017-12-19T12:31:24.570Z"}}},{"id":"5f4be5bd-0c83-417a-b744-7d8c49636ab1","type":"field","field_type":"string","slug":"background_image","name":"Background Image","description":"The background image for the category","required":false,"default":null,"enabled":true,"validation_rules":[],"order":null,"omit_null":false,"links":{"self":"https://useast.api.elasticpath.com/v2/flows/248c7776-bd9f-4075-8980-461b02ed3757/fields/5f4be5bd-0c83-417a-b744-7d8c49636ab1"},"relationships":{"flow":{"data":{"id":"248c7776-bd9f-4075-8980-461b02ed3757","type":"flow"}}},"meta":{"owner":"organization","timestamps":{"created_at":"2018-03-29T10:33:24.056Z","updated_at":"2018-03-29T10:33:24.056Z"}}}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Fields

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Fields"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint retrieves all fields in a flow. 
- For Product Experience Manager, this endpoint retrieves all attributes in a template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"description":"Filter resources using the filter query parameter. See [**Filtering**](/guides/Getting-Started/filtering).","schema":{"type":"string","example":"eq(owner,organization)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Field","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["field"]},"field_type":{"type":"string","description":"This field is immutable and cannot be updated. You can have the following field types:\n- `string`\n- `integer`\n- `boolean`\n- `float`\n- `date`\n- `relationship`\n","examples":["integer"]},"slug":{"type":"string","description":"A short description for a field/attribute.","examples":["product-rating"]},"name":{"type":"string","description":"The name of a field/attribute.","examples":["Product Rating"]},"description":{"type":"string","description":"A short description of a field/attribute.","examples":["Average rating as given by our users"]},"required":{"type":"boolean","description":"`true` if required on input, `false` if not. Always `false` if the `field_type` is a relationship.\n","examples":[true]},"default":{"type":["boolean","number","string","null"],"description":"A default value if none is supplied and a field/attribute is not required.","examples":[1]},"enabled":{"type":"boolean","examples":[true]},"order":{"type":["number","null"],"description":"Denotes the order in which this field is returned relative to the rest of the flow/template fields/attributes.","examples":[1]},"omit_null":{"type":"boolean","description":"Hide this field/attribute from responses if the value is `null`.","examples":[true]},"validation_rules":{"type":"array","items":{"type":"object","description":"An array of validation rule objects. See [Field/attribute Validation Rules](#fieldattribute-validation-rules).","properties":{"type":{"type":"string","description":"The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.","example":"enum","enum":["enum","email","slug","between","one-to-many","one-to-one"]},"options":{"anyOf":[{"type":"array","description":"An array of valid string values.","items":{"type":"string"}},{"type":"object","description":"An object containing `from` and `to` numbers.","properties":{"from":{"type":["number","string"],"example":1},"to":{"type":["number","string"],"example":5}}}]},"to":{"type":"string","example":"customer"}},"title":"FieldValidationRules"}},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"links":{"type":"object","description":"Links allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Listing pages use the following:\n\n| Property | Description |\n| --- | --- |\n| `current` | Always the current page |\n| `first` | Always the first page |\n| `last` | `null` if there is only one page. |\n| `previous` | `null` if you are on the first page. |\n| `next` | `null` if there is only one page. |\n","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/3cf3ad3f-b12c-4a08-a6ab-05e6aab0122c/fields/c1c788d1-f1c7-4b90-938f-f158f3353c66"}},"title":"FieldLinks"},"relationships":{"type":"object","description":"Relationships are established between different flow/template entities. For example, a field/attribute is related to a flow/template, as the field/attribute is attached to the flow/template.","required":["flow"],"properties":{"flow":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"flow"}}}}}},"title":"FieldRelationships"}}}}}},"examples":{"default":{"value":{"data":[{"id":"e88d03d3-d46e-40d0-8302-25e6b5b1bd33","type":"field","field_type":"boolean","slug":"on_sale","name":"On Sale?","description":"Is this on sale?","required":false,"default":null,"enabled":true,"order":null,"omit_null":false,"validation_rules":[],"links":{"self":"https://useast.api.elasticpath.com/v2/flows/9d69c6cf-aaee-4dc6-8908-d2bd053446a2/fields/e88d03d3-d46e-40d0-8302-25e6b5b1bd33"},"relationships":{"flow":{"data":{"id":"9d69c6cf-aaee-4dc6-8908-d2bd053446a2","type":"flow"}}},"meta":{"owner":"organization","timestamps":{"created_at":"2018-08-23T10:28:43.609Z","updated_at":"2018-08-23T10:28:43.609Z"}}}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Flows

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Flows"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/flows"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint retrieves a list of flows.
- For Product Experience Manager, this endpoint retrieves a list of templates.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"description":"Filter resources using the filter query parameter. See [**Filtering**](/guides/Getting-Started/filtering).","schema":{"type":"string","example":"eq(owner,organization)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Flows","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"A unique identifier for a flow/template.","example":"flow"},"name":{"type":"string","description":"The name of a flow/template.","example":"Products"},"slug":{"type":"string","description":"A unique identifier of a flow/template.","example":"products"},"description":{"type":"string","description":"A short description for a flow/template.","example":"Extends the default product object"},"enabled":{"type":"boolean","example":true},"links":{"type":"object","description":"Link to the current resource.","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84"}},"title":"SelfLink"},"relationships":{"type":"object","description":"Relationships are established between different flows/templates entities. For example, a field and an entry are related to a flow as both are attached to it.","properties":{"fields":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Relationships","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"brand"}}}}}}},"title":"FlowsRelationships"},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"}}}}}},"examples":{"default":{"value":{"data":[{"id":"6d320b42-237d-4474-8452-d49f884d4ae1","type":"flow","name":"Products-1","slug":"products-1","description":"Extends the default product object","enabled":true,"links":{"self":"https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1"},"relationships":{},"meta":{"owner":"organization","timestamps":{"created_at":"2018-05-10T18:04:26.623Z","updated_at":"2018-05-10T18:04:26.623Z"}}}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Entry

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Entry"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/flows/{flowSlug}/entries/{flowEntryID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint retrieves an entry from a flow.
- For Product Experience Manager, this endpoint retrieves an entry from a template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug for the flow/template.","style":"simple","schema":{"type":"string"}},{"name":"flowEntryID","in":"path","required":true,"description":"The ID of the entry.","style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Entry","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"entry"},"links":{"type":"object","description":"Link to the current resource.","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84"}},"title":"SelfLink"},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"relationships":{"type":"object","additionalProperties":true,"description":"Dynamic relationship fields keyed by field slug."}},"additionalProperties":{"description":"There can be a `:fieldSlug` attribute for each field/attribute attached to a flow/template. The type depends on the field type."}}}},"examples":{"default":{"value":{"data":{"id":"4abb8316-d0a2-4c91-bf29-4d19ba932227","type":"entry","meta":{"owner":"organization","timestamps":{"created_at":"2018-05-10T15:28:59.192Z","updated_at":"2018-05-10T15:28:59.192Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/flows/products/entries/4abb8316-d0a2-4c91-bf29-4d19ba932227"}}}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a Field

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Field"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/fields/{flowFieldID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint updates a field.
- For Product Experience Manager, this endpoint updates an attribute.

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the field/attribute is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowFieldID","description":"The unique identifier for the flow/template to which the field/attribute you want to update belongs.","in":"path","required":true,"style":"simple","schema":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"allOf":[{"title":"FieldUpdateRequest","type":"object","properties":{"data":{"type":"object","properties":{"default":{"type":"number","description":"A default value if none is supplied and the field/attribute is required.","examples":[1]},"description":{"type":"string","description":"A description for a field/attribute.","examples":["Average rating as given by our users"]},"field_type":{"type":"string","description":"This field is immutable and cannot be updated. The type of field: \n- `string`\n- `integer`\n- `boolean`\n- `float`\n- `date`\n- `relationship`\n","examples":["integer"]},"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"name":{"type":"string","description":"The name of a field/attribute.","examples":["Product Rating"]},"required":{"type":"boolean","description":"`true` if required on input, `false` if not. Always `false` if the `field_type` is `relationship`.\n","examples":[true]},"slug":{"type":"string","description":"A unique identifier of a field/attribute.","examples":["product-rating"]},"enabled":{"type":"boolean","examples":[true]},"type":{"type":"string","description":"Represents the object being returned.","examples":["field"]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"default":1,"description":"Average rating as given by our users","field_type":"integer","id":"{{flowFieldID}}","name":"Product Rating","required":true,"enabled":true,"slug":"product-rating","type":"field"}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Field","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["field"]},"field_type":{"type":"string","description":"This field is immutable and cannot be updated. You can have the following field types:\n- `string`\n- `integer`\n- `boolean`\n- `float`\n- `date`\n- `relationship`\n","examples":["integer"]},"slug":{"type":"string","description":"A short description for a field/attribute.","examples":["product-rating"]},"name":{"type":"string","description":"The name of a field/attribute.","examples":["Product Rating"]},"description":{"type":"string","description":"A short description of a field/attribute.","examples":["Average rating as given by our users"]},"required":{"type":"boolean","description":"`true` if required on input, `false` if not. Always `false` if the `field_type` is a relationship.\n","examples":[true]},"default":{"type":["boolean","number","string","null"],"description":"A default value if none is supplied and a field/attribute is not required.","examples":[1]},"enabled":{"type":"boolean","examples":[true]},"order":{"type":["number","null"],"description":"Denotes the order in which this field is returned relative to the rest of the flow/template fields/attributes.","examples":[1]},"omit_null":{"type":"boolean","description":"Hide this field/attribute from responses if the value is `null`.","examples":[true]},"validation_rules":{"type":"array","items":{"type":"object","description":"An array of validation rule objects. See [Field/attribute Validation Rules](#fieldattribute-validation-rules).","properties":{"type":{"type":"string","description":"The validation you use depends on the `field_type` of the field/attribute. Each validation rule is expressed as a validation rule object.","example":"enum","enum":["enum","email","slug","between","one-to-many","one-to-one"]},"options":{"anyOf":[{"type":"array","description":"An array of valid string values.","items":{"type":"string"}},{"type":"object","description":"An object containing `from` and `to` numbers.","properties":{"from":{"type":["number","string"],"example":1},"to":{"type":["number","string"],"example":5}}}]},"to":{"type":"string","example":"customer"}},"title":"FieldValidationRules"}},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"links":{"type":"object","description":"Links allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Listing pages use the following:\n\n| Property | Description |\n| --- | --- |\n| `current` | Always the current page |\n| `first` | Always the first page |\n| `last` | `null` if there is only one page. |\n| `previous` | `null` if you are on the first page. |\n| `next` | `null` if there is only one page. |\n","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/3cf3ad3f-b12c-4a08-a6ab-05e6aab0122c/fields/c1c788d1-f1c7-4b90-938f-f158f3353c66"}},"title":"FieldLinks"},"relationships":{"type":"object","description":"Relationships are established between different flow/template entities. For example, a field/attribute is related to a flow/template, as the field/attribute is attached to the flow/template.","required":["flow"],"properties":{"flow":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id"],"properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"flow"}}}}}},"title":"FieldRelationships"}}}}},"examples":{"default":{"value":{"data":{"id":"102b2087-d56a-45e7-bf1c-e9517716abb3","type":"field","field_type":"integer","slug":"start-of-life","name":"start-of-life","description":"day the iphone will work","required":true,"default":"2018-01-01","enabled":true,"validation_rules":[{"type":"between","options":{"from":1,"to":5}}],"order":1,"omit_null":false,"links":{"self":"https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1/fields/102b2087-d56a-45e7-bf1c-e9517716abb3"},"relationships":{"flow":{"data":{"id":"6d320b42-237d-4474-8452-d49f884d4ae1","type":"flow"}}},"meta":{"owner":"organization","timestamps":{"created_at":"2018-05-10T18:19:11.559Z","updated_at":"2018-05-10T18:36:01.208Z"}}}}}}}}},"403":{"description":"Forbidden. The request was valid but the token does not have permission to perform this operation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"forbidden":{"value":{"errors":[{"title":"Forbidden","status":"403"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a Flow

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Flow"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/flows/{flowID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint updates a flow. 
- For Product Experience Manager, this endpoint updates a template. 

 Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the flow/template is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowID","description":"The unique identifier of the flow/template you want to update.","in":"path","required":true,"style":"simple","schema":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"allOf":[{"title":"FlowsUpdateRequest","type":"object","properties":{"data":{"type":"object","properties":{"description":{"type":"string","description":"A brief description of a flow/template outlining details such as purpose, usage instructions, and so on.","examples":["Extends the default product object"]},"enabled":{"type":"boolean","examples":[true]},"name":{"type":"string","description":"The name of a flow/template.","examples":["Products"]},"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"slug":{"type":"string","description":"A unique slug identifier for a flow/template.","examples":["products"]},"type":{"type":"string","description":"Represents the type of object being returned.","examples":["flow"]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"id":"25617d3e-14a6-434c-bfab-3fda87517aaf","description":"Extends the default product object","enabled":true,"name":"Products","slug":"products","type":"flow"}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Flows","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"A unique identifier for a flow/template.","example":"flow"},"name":{"type":"string","description":"The name of a flow/template.","example":"Products"},"slug":{"type":"string","description":"A unique identifier of a flow/template.","example":"products"},"description":{"type":"string","description":"A short description for a flow/template.","example":"Extends the default product object"},"enabled":{"type":"boolean","example":true},"links":{"type":"object","description":"Link to the current resource.","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84"}},"title":"SelfLink"},"relationships":{"type":"object","description":"Relationships are established between different flows/templates entities. For example, a field and an entry are related to a flow as both are attached to it.","properties":{"fields":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Relationships","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"brand"}}}}}}},"title":"FlowsRelationships"},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"}}}}},"examples":{"default":{"value":{"data":{"id":"6d320b42-237d-4474-8452-d49f884d4ae1","type":"flow","name":"extraFieldRenamed","slug":"products-1","description":"Extends the default product object","enabled":true,"links":{"self":"https://useast.api.elasticpath.com/v2/flows/6d320b42-237d-4474-8452-d49f884d4ae1"},"relationships":{},"meta":{"owner":"store","timestamps":{"created_at":"2018-05-10T18:04:26.623Z","updated_at":"2018-05-10T18:11:47.469Z"}}}}}}}}},"403":{"description":"Forbidden. The request was valid but the token does not have permission to perform this operation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"forbidden":{"value":{"errors":[{"title":"Forbidden","status":"403"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an Entry Relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Entry Relationship"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/flows/{flowSlug}/entries/{flowEntryID}/relationships/{flowFieldSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- In Commerce, updates an entry relationship to one or more resources. If any relationships already exist, the ones made in the request are added to them.
- In Product Experience Manager, updates an entry relationship with the product to which you want to associate the template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug of the flow/template that the entry belongs to.","style":"simple","schema":{"type":"string"}},{"name":"flowFieldSlug","in":"path","required":true,"description":"The slug of the field/attribute that the relationship belongs to.","style":"simple","schema":{"type":"string"}},{"name":"flowEntryID","in":"path","required":true,"description":"The ID of the entry you are requesting.","style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"allOf":[{"title":"FlowsEntriesRelationshipsFieldSlugRequest","type":"object","properties":{"data":{"type":"array","description":"The data to be stored.","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"The resource type of the object.","examples":["customer"]}}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":[{"id":"{RESOURCE_ID}","type":"{RESOURCE_TYPE}"},{"id":"{RESOURCE_ID}","type":"{RESOURCE_TYPE}"}]}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"title":"Relationships","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"brand"}}}}}},"examples":{"default":{"value":{"data":[{"type":"brand","id":"0d28e5b6-f615-4e1c-b038-275cfde97927"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an Entry

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Entry"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/flows/{flowSlug}/entries/{flowEntryID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- For Commerce, this endpoint updates an entry for a flow.
- For Product Experience Manager, this endpoint updates an entry for a template.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"flowSlug","in":"path","required":true,"description":"The slug for the flow/template.","style":"simple","schema":{"type":"string"}},{"name":"flowEntryID","in":"path","required":true,"description":"The ID of the entry.","style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"FlowsEntriesUpdateRequest","type":"object","properties":{"data":{"type":"object","properties":{"FIELD1_SLUG":{"type":"string","description":"The field slug for each field/attribute in a flow/template and the corresponding value for the entry. You can have multiple field slugs if they are related to the flow/template.","examples":["value1"]},"FIELD2_SLUG":{"type":"string","description":"The field slug for each field/attribute in a flow/template and the corresponding value for the entry. You can have multiple field slugs if they are related to the flow/template.","examples":["value2"]},"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of the resource object.","examples":["entry"]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"FIELD1_SLUG":"value1","FIELD2_SLUG":"value2","id":"{{entryID}}","type":"entry"}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","headers":{},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"title":"Entry","type":"object","properties":{"id":{"type":"string","description":"A unique identifier for a resource.","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","description":"Represents the type of object being returned.","example":"entry"},"links":{"type":"object","description":"Link to the current resource.","properties":{"self":{"type":"string","example":"https://euwest.api.elasticpath.com/v2/flows/d2a9b22a-b4b0-456b-bbc7-d8723aaffa84"}},"title":"SelfLink"},"meta":{"type":"object","properties":{"owner":{"type":"string","description":"The resource owner, either `organization` or `store`.","example":"enum","enum":["store","organization"]},"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time a resource is created.","example":"2023-10-11T13:02:25.293Z"},"updated_at":{"type":"string","description":"The date and time a resource is updated.","example":"2023-10-11T13:02:25.293Z"}}}},"title":"Meta"},"relationships":{"type":"object","additionalProperties":true,"description":"Dynamic relationship fields keyed by field slug."}},"additionalProperties":{"description":"There can be a `:fieldSlug` attribute for each field/attribute attached to a flow/template. The type depends on the field type."}}}},"examples":{"default":{"value":{"data":{"id":"03224af8-da41-4761-99fb-a125fa81ed99","type":"entry","brand-image":"a new image","meta":{"owner":"organization","timestamps":{"created_at":"2018-06-06T14:42:39.312Z","updated_at":"2018-06-06T14:42:39.312Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/flows/brands/entries/03224af8-da41-4761-99fb-a125fa81ed99"}}}}}}}},"403":{"description":"Forbidden. The request was valid but the token does not have permission to perform this operation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"forbidden":{"value":{"errors":[{"title":"Forbidden","status":"403"}]}}}}}},"404":{"description":"Bad request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create an integration

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an integration"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/integrations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create an integration.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","observers","integration_type","name","configuration"],"properties":{"type":{"description":"The type represents the object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"name":{"type":"string","example":"Order shipping notification","description":"The name of the integration."},"description":{"type":"string","example":"Send a shipping notification via email with discount code","description":"A description of what the integration is for."},"enabled":{"type":"boolean","example":true,"description":"Whether the integration is enabled."},"integration_type":{"type":"string","description":"Specifies how the event is delivered. The options are `webhook`, `aws-sqs`, or `stomp`.","example":"webhook","enum":["webhook","aws_sqs","stomp"],"default":"webhook"},"observes":{"description":"The list of events you want to observe. See [**Observable Events**](#observable-events).","type":"array","items":{"type":"string"}},"configuration":{"description":"The content of the configuration object depends on the value of `integration_type`.","type":"object","oneOf":[{"required":["url","aws_access_key_id","aws_secret_access_key","region"],"properties":{"url":{"type":"string","format":"uri","example":"https://sqs.eu-west-1.amazonaws.com/123456789/epcc-external-queue","description":"The required SQS queue URL."},"aws_access_key_id":{"type":"string","example":"****************JIMB","description":"The required AWS access key ID."},"aws_secret_access_key":{"type":"string","example":"************************************HK4o","description":"The required AWS secret key ID."},"region":{"type":"string","example":"eu-west-1","description":"The required AWS region."}},"title":"AWSSQSConfigurationObject"},{"required":["url"],"properties":{"url":{"type":"string","example":"https://yourwebsite.com/order-created-notification","description":"A required URL that the integration fires.","format":"uri"},"secret_key":{"type":"string","example":"secret_key_to_validate_on_your_endpoint","description":"An optional header. Useful to authenticate the response came from Elastic Path. This is sent as `X-MOLTIN-SECRET-KEY`."}},"title":"WebhookConfigurationObject"},{"required":["url"],"properties":{"username":{"type":"string","example":"epcc-integration-1","description":"The username used to authenticate against a STOMP server."},"password":{"type":"string","example":"****************************CDKn","description":"The password used to authenticate against a STOMP server."},"destination":{"type":"string","example":"/queue/epcc-integrations.order-created","description":"The destination in the messaging queuing system."},"addresses":{"type":"array","items":{"type":"string","format":"uri"},"example":["stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-2.mq.us-west-2.amazonaws.com:61614","stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-1.mq.us-west-2.amazonaws.com:61614"],"description":"The addresses that correspond with the destination name."}},"title":"STOMPConfigurationObject"}]}},"title":"IntegrationCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Integration created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"properties":{"id":{"description":"The unique identifier of the integration.","type":"string","example":"2da46671-b4c2-44ac-b133-d1221aafc77b"},"type":{"description":"The type represents the object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"name":{"type":"string","example":"Order shipping notification","description":"The name of the integration."},"description":{"type":"string","example":"Send a shipping notification via email with discount code","description":"A description of what the integration is for."},"enabled":{"type":"boolean","example":true,"description":"Whether the integration is enabled."},"integration_type":{"type":"string","example":"webhook","description":"Specifies how the event is delivered. The options are `webhook`, `aws-sqs`, or `stomp`.","enum":["webhook","aws_sqs","stomp"],"default":"webhook"},"observes":{"description":"The list of events you want to observe. See [**Observable Events**](#observable-events).","type":"array","items":{"type":"string"}},"configuration":{"type":"object","oneOf":[{"required":["url","aws_access_key_id","aws_secret_access_key","region"],"properties":{"url":{"type":"string","format":"uri","example":"https://sqs.eu-west-1.amazonaws.com/123456789/epcc-external-queue","description":"The required SQS queue URL."},"aws_access_key_id":{"type":"string","example":"****************JIMB","description":"The required AWS access key ID."},"aws_secret_access_key":{"type":"string","example":"************************************HK4o","description":"The required AWS secret key ID."},"region":{"type":"string","example":"eu-west-1","description":"The required AWS region."}},"title":"AWSSQSConfigurationObject"},{"required":["url"],"properties":{"url":{"type":"string","example":"https://yourwebsite.com/order-created-notification","description":"A required URL that the integration fires.","format":"uri"},"secret_key":{"type":"string","example":"secret_key_to_validate_on_your_endpoint","description":"An optional header. Useful to authenticate the response came from Elastic Path. This is sent as `X-MOLTIN-SECRET-KEY`."}},"title":"WebhookConfigurationObject"},{"required":["url"],"properties":{"username":{"type":"string","example":"epcc-integration-1","description":"The username used to authenticate against a STOMP server."},"password":{"type":"string","example":"****************************CDKn","description":"The password used to authenticate against a STOMP server."},"destination":{"type":"string","example":"/queue/epcc-integrations.order-created","description":"The destination in the messaging queuing system."},"addresses":{"type":"array","items":{"type":"string","format":"uri"},"example":["stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-2.mq.us-west-2.amazonaws.com:61614","stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-1.mq.us-west-2.amazonaws.com:61614"],"description":"The addresses that correspond with the destination name."}},"title":"STOMPConfigurationObject"}]}},"title":"Integration"},{"type":"object","properties":{"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"?page[offset]=0&page[limit]=25","title":"LinkURI"}}}},"title":"Links"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"description":"The date and time a transaction is created.","properties":{"created_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"updated_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"Timestamps"}}}},"title":"Meta"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":400,"detail":"Your request was invalid"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete an integration

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an integration"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/integrations/{integration_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the Integration for the given UUID

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"integration_uuid","in":"path","description":"The unique identifier of the integration.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Integration was successfully deleted"},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an integration

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an integration"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/integrations/{integration_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the integration for the given UUID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"integration_uuid","in":"path","description":"The unique identifier of the integration.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. An integration is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"properties":{"id":{"description":"The unique identifier of the integration.","type":"string","example":"2da46671-b4c2-44ac-b133-d1221aafc77b"},"type":{"description":"The type represents the object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"name":{"type":"string","example":"Order shipping notification","description":"The name of the integration."},"description":{"type":"string","example":"Send a shipping notification via email with discount code","description":"A description of what the integration is for."},"enabled":{"type":"boolean","example":true,"description":"Whether the integration is enabled."},"integration_type":{"type":"string","example":"webhook","description":"Specifies how the event is delivered. The options are `webhook`, `aws-sqs`, or `stomp`.","enum":["webhook","aws_sqs","stomp"],"default":"webhook"},"observes":{"description":"The list of events you want to observe. See [**Observable Events**](#observable-events).","type":"array","items":{"type":"string"}},"configuration":{"type":"object","oneOf":[{"required":["url","aws_access_key_id","aws_secret_access_key","region"],"properties":{"url":{"type":"string","format":"uri","example":"https://sqs.eu-west-1.amazonaws.com/123456789/epcc-external-queue","description":"The required SQS queue URL."},"aws_access_key_id":{"type":"string","example":"****************JIMB","description":"The required AWS access key ID."},"aws_secret_access_key":{"type":"string","example":"************************************HK4o","description":"The required AWS secret key ID."},"region":{"type":"string","example":"eu-west-1","description":"The required AWS region."}},"title":"AWSSQSConfigurationObject"},{"required":["url"],"properties":{"url":{"type":"string","example":"https://yourwebsite.com/order-created-notification","description":"A required URL that the integration fires.","format":"uri"},"secret_key":{"type":"string","example":"secret_key_to_validate_on_your_endpoint","description":"An optional header. Useful to authenticate the response came from Elastic Path. This is sent as `X-MOLTIN-SECRET-KEY`."}},"title":"WebhookConfigurationObject"},{"required":["url"],"properties":{"username":{"type":"string","example":"epcc-integration-1","description":"The username used to authenticate against a STOMP server."},"password":{"type":"string","example":"****************************CDKn","description":"The password used to authenticate against a STOMP server."},"destination":{"type":"string","example":"/queue/epcc-integrations.order-created","description":"The destination in the messaging queuing system."},"addresses":{"type":"array","items":{"type":"string","format":"uri"},"example":["stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-2.mq.us-west-2.amazonaws.com:61614","stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-1.mq.us-west-2.amazonaws.com:61614"],"description":"The addresses that correspond with the destination name."}},"title":"STOMPConfigurationObject"}]}},"title":"Integration"},{"type":"object","properties":{"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"?page[offset]=0&page[limit]=25","title":"LinkURI"}}}},"title":"Links"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"description":"The date and time a transaction is created.","properties":{"created_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"updated_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"Timestamps"}}}},"title":"Meta"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":404,"detail":"The resource could not be found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## Integrations Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/integrations/openapi.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Integrations Introduction"}
>
</Heading>

You can integrate Commerce with your external systems like enterprise resource planning, order management, fulfilment, and other systems, ensuring that buying is quick and easy for your shoppers.
 
Events are actions that occur in your commerce workflow, such as a customer changing their address or an order changing status from created to paid. You can create custom functions that perform additional processing outside of Commerce, and create integrations so that when an event occurs in your store, the custom function is run.

For example:

- When a customer updates their address, the Customer Relationship Management system is updated with the change.
- When an order status changes to paid, the affected stock in an inventory management system is reduced by the number of items in the order.
 
Events are processed concurrently. This means that events may not be delivered in the order they are created. For example, if the status of an order is updated multiple times, the events may not be delivered in the same sequence they were updated. Integration events operate on an "at least once" delivery policy. We aim to deliver messages within 15 seconds except in cases of high load. Ensure that you design your receiving code accordingly.

:::note
 
For a list of all the events that can be used, see [Observable Events](#observable-events).
 
:::

You can integrate Commerce with your external systems using:

- Webhooks
- Message Queuing Services
 
### Webhooks
 
You can use Webhooks to deliver Commerce events to a configured HTTP endpoint.
 
### Message Queuing Services
 
You can deliver Commerce events to messages queues through the following message queuing services:
 
- Amazon Simple Queuing Service (SQS)
- Message queuing services that support the Message Simple Text Orientated Messaging Protocol (STOMP), for example, Amazon MQ.
 
:::note
 
You can integrate Amazon SQS and message queuing services that support STOMP through the Integrations API. You can view the integration details in Commerce Manager > **SYSTEM** > **Store Settings** > **Webhooks**. For more information, see [Create an integration](/docs/api/integrations/create-integration).
 
:::
 
### Integration Types
 
Commerce supports the following integration types:

- Using [webhooks](/docs/api/integrations/create-integration), you can have Commerce deliver events to a configured HTTP endpoint.
 
:::caution
 
Webhooks that return anything other than a 2XX status code, or take more than 10 seconds to respond, are considered failed.

- Using [message queuing services](#message-queuing-services), you can deliver Commerce events to a message queue. The advantages of using message queuing services over webhooks are:

     - A temporary failure of a webhook endpoint can result in lost events. However, if messages are on your own queue, you can leave the event on the queue to retry later.
     - If events take a long time to process, a webhook can timeout, but delivery to a queue is always going to take the same amount of time.
 
:::

### Webhooks

An integration with an `integration_type` of [`webhook`](/docs/api/integrations/create-integration) delivers its events to a configured HTTP endpoint.
 
### Message Queuing Services

Elastic Path allows you to integrate with the following message queuing services:

- Amazon Simple Message Queuing Service (SQS).
- Message queuing services that use Simple Text Orientated Messaging Protocol (STOMP), for example, Amazon MQ.

:::caution
 
You can integrate Amazon SQS and message queuing services that support STOMP through the Integrations API. You can view the integration details in Commerce Manager > **SYSTEM** > **Store Settings** > **Webhooks**. For more information, see [Create an integration](/docs/api/integrations/create-integration).
 
:::
 
#### Amazon Simple Message Queuing Service (SQS)

An integration with an `integration_type` of [`aws_sqs`](/docs/api/integrations/create-integration) delivers its events directly into the configured AWS SQS queue. These messages can be processed by any appropriate means, such as a Lambda function.

For more information about creating Simple Queue Service (SQS) queues, see the [Simple Queue Service (SQS)](https://elasticpath.dev/guides/How-To/Integrations/sqs-queues) and [SQS Events with CloudFormation](https://elasticpath.dev/guides/How-To/Integrations/sqs-queues-cloudformation) sections.
 
#### Simple Text Orientated Messaging Protocol (STOMP)

An integration with the [`stomp`](/docs/api/integrations/create-integration) integration type delivers its events directly into a configured queue. Any message queuing service that uses STOMP, such as Amazon MQ, can process these messages.

For more information, see the documentation provided with the message queuing service you are using.
 
### Webhooks

The payload delivered to your webhook `url` contains information about the fired event.

The payload attributes and types are defined in the following table.

| Attribute      | Type                             | Description                                                                                       |
| :------------- | :------------------------------- | :------------------------------------------------------------------------------------------------ |
| `id`           | `string`                         | A unique ID for this event.                                                                       |
| `integration`  | `object`                         | The events `integration_type` being fired.                                                        |
| `triggered_by` | `string` | The [observable events](#observable-events) that triggered this event.                           |
| `attempt`      | `integer`                        | The number of attempts to deliver this event.                                                     |
| `resources`    | `string`                         | The resources affected by this event. This field is now deprecated. Please use `payload` instead. |
| `payload`      | `object`                         | The resources affected by this event.                                                             |

:::note
Store-level events contain `store_id` and `org_id` whereas, organization-level events contain only `org_id`.
 
:::

### Example: Typical payload

The following example payload [observes](#observable-events) the `order.paid` event. The configured URL receives the following payload.
 
```javascript
{
 "id": "21a361c9-b117-4d16-be2d-5ed2dbdaa95b",
 "triggered_by": "order.paid",
 "attempt": 1,
 "integration": {
   "id": "af7bbcc7-f77f-4a8f-abdb-4f039c5c9d81",
   "integration_type": "webhook",
   "name": "Order paid notification",
   "description": "Fire an event on order paid"
 },
 "resources": "{\"data\":{\"type\":\"order\",\"id\":\"1d67160d-dacb-43ed-80ef-c3c4e7ddf764\",\"status\":\"complete\",\"payment\":\"paid\",\"shipping\":\"unfulfilled\",\"customer\":{\"name\":\"Ron Swanson\",\"email\":\"ron.swanson@moltin.com\"},\"shipping_address\":{\"first_name\":\"Jack\",\"last_name\":\"Macdowall\",\"phone_number\":\"123456789\",\"company_name\":\"Macdowalls\",\"line_1\":\"Second Floor, British India House\",\"line_2\":\"15 Carliol Square\",\"city\":\"Newcastle upon Tyne\",\"postcode\":\"NE1 6UF\",\"county\":\"Tyne and Wear\",\"country\":\"GB\",\"instructions\":\"Leave in porch\"},\"billing_address\":{\"first_name\":\"Jack\",\"last_name\":\"Macdowall\",\"company_name\":\"Macdowalls\",\"line_1\":\"Second Floor, British India House\",\"line_2\":\"15 Carliol Square\",\"city\":\"Newcastle upon Tyne\",\"postcode\":\"NE1 6UF\",\"county\":\"Tyne and Wear\",\"country\":\"GB\"},\"links\":{},\"meta\":{\"display_price\":{\"with_tax\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"},\"without_tax\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"},\"tax\":{\"amount\":0,\"currency\":\"GBP\",\"formatted\":\"£0.00\"}},\"timestamps\":{\"created_at\":\"2019-07-04T11:12:23Z\",\"updated_at\":\"2019-07-04T11:12:23Z\"}},\"relationships\":{\"items\":{\"data\":[{\"type\":\"item\",\"id\":\"395763ee-1878-4aa0-a7a2-8d4877310d6b\"}]}}},\"included\":{\"items\":[{\"type\":\"order_item\",\"id\":\"395763ee-1878-4aa0-a7a2-8d4877310d6b\",\"quantity\":1,\"product_id\":\"4f28f222-aa5b-442c-9ce9-c223dc7cf15a\",\"name\":\"Spam Fritters\",\"sku\":\"spam-fritters-0716\",\"unit_price\":{\"amount\":10000,\"currency\":\"GBP\",\"includes_tax\":false},\"value\":{\"amount\":10000,\"currency\":\"GBP\",\"includes_tax\":false},\"links\":{},\"meta\":{\"display_price\":{\"with_tax\":{\"unit\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"},\"value\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"}},\"without_tax\":{\"unit\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"},\"value\":{\"amount\":10000,\"currency\":\"GBP\",\"formatted\":\"£100.00\"}},\"tax\":{\"unit\":{\"amount\":0,\"currency\":\"GBP\",\"formatted\":\"£0.00\"},\"value\":{\"amount\":0,\"currency\":\"GBP\",\"formatted\":\"£0.00\"}}},\"timestamps\":{\"created_at\":\"2019-07-04T11:12:23Z\",\"updated_at\":\"2019-07-04T11:12:23Z\"}},\"relationships\":{\"cart_item\":{\"data\":{\"type\":\"cart_item\",\"id\":\"a498b15a-2cc7-49ea-93b3-22143bb403ac\"}}}}]}}",
 "payload": {
   "data": {
     "type": "order",
     "id": "1d67160d-dacb-43ed-80ef-c3c4e7ddf764",
     "status": "complete",
     "payment": "paid",
     "shipping": "unfulfilled",
     "customer": {
       "name": "Ron Swanson",
       "email": "ron.swanson@moltin.com"
     },
     "shipping_address": {
       "first_name": "Jack",
       "last_name": "Macdowall",
       "phone_number": "123456789",
       "company_name": "Macdowalls",
       "line_1": "Second Floor, British India House",
       "line_2": "15 Carliol Square",
       "city": "Newcastle upon Tyne",
       "postcode": "NE1 6UF",
       "county": "Tyne and Wear",
       "country": "GB",
       "instructions": "Leave in porch"
     },
     "billing_address": {
       "first_name": "Jack",
       "last_name": "Macdowall",
       "company_name": "Macdowalls",
       "line_1": "Second Floor, British India House",
       "line_2": "15 Carliol Square",
       "city": "Newcastle upon Tyne",
       "postcode": "NE1 6UF",
       "county": "Tyne and Wear",
       "country": "GB"
     },
     "links": {},
     "meta": {
       "display_price": {
         "with_tax": {
           "amount": 10000,
           "currency": "GBP",
           "formatted": "£100.00"
         },
         "without_tax": {
           "amount": 10000,
           "currency": "GBP",
           "formatted": "£100.00"
         },
         "tax": {
           "amount": 0,
           "currency": "GBP",
           "formatted": "£0.00"
         }
       },
       "timestamps": {
         "created_at": "2019-07-04T11:12:23Z",
         "updated_at": "2019-07-04T11:12:23Z"
       }
     },
     "relationships": {
       "items": {
         "data": [
           {
             "type": "item",
             "id": "395763ee-1878-4aa0-a7a2-8d4877310d6b"
           }
         ]
       }
     }
   },
   "included": {
     "items": [
       {
         "type": "order_item",
         "id": "395763ee-1878-4aa0-a7a2-8d4877310d6b",
         "quantity": 1,
         "product_id": "4f28f222-aa5b-442c-9ce9-c223dc7cf15a",
         "name": "Spam Fritters",
         "sku": "spam-fritters-0716",
         "unit_price": {
           "amount": 10000,
           "currency": "GBP",
           "includes_tax": false
         },
         "value": {
           "amount": 10000,
           "currency": "GBP",
           "includes_tax": false
         },
         "links": {},
         "meta": {
           "display_price": {
             "with_tax": {
               "unit": {
                 "amount": 10000,
                 "currency": "GBP",
                 "formatted": "£100.00"
               },
               "value": {
                 "amount": 10000,
                 "currency": "GBP",
                 "formatted": "£100.00"
               }
             },
             "without_tax": {
               "unit": {
                 "amount": 10000,
                 "currency": "GBP",
                 "formatted": "£100.00"
               },
               "value": {
                 "amount": 10000,
                 "currency": "GBP",
                 "formatted": "£100.00"
               }
             },
             "tax": {
               "unit": {
                 "amount": 0,
                 "currency": "GBP",
                 "formatted": "£0.00"
               },
               "value": {
                 "amount": 0,
                 "currency": "GBP",
                 "formatted": "£0.00"
               }
             }
           },
           "timestamps": {
             "created_at": "2019-07-04T11:12:23Z",
             "updated_at": "2019-07-04T11:12:23Z"
           }
         },
         "relationships": {
           "cart_item": {
             "data": {
               "type": "cart_item",
               "id": "a498b15a-2cc7-49ea-93b3-22143bb403ac"
             }
           }
         }
       }
     ]
   }
 },
 "configuration": {
   "secret_key": "secret_squirrel",
   "url": "https://webhook.url"
 }
}
```

### Example: Deleted resources payload

When resources are deleted and you observe an event, you receive a payload which **only** contains the resource type and ID.
 
```javascript
{
 "id": "c138854a-5311-4543-a368-01e099f5519b",
 "triggered_by": "product.deleted",
 "attempt": 1,
 "integration": {
   "id": "4596d5e1-26b6-444a-964d-2b6ec46477fd",
   "integration_type": "webhook",
   "name": "Product deleted notification",
   "description": "Let me know when products are deleted from my store."
 },
 "resources": {
   "id": "a34a378b-2c39-41e4-a240-6b7e65f5bb55",
   "type": "product"
 },
 "payload": {
   "type": "product",
   "id": "a34a378b-2c39-41e4-a240-6b7e65f5bb55"
 },
 "configuration": {
   "secret_key": "secret_squirrel",
   "url": "https://webhook.url"
 }
}
```

### Message Queue Services

The payload of messages delivered to your message queue contains information about the fired event. The information takes the form of a standard cloud event.

The following table defines the payload attributes and types:

| Attribute       | Type                             | Description                                                             |
| :-------------- | :------------------------------- | :---------------------------------------------------------------------- |
| `id`            | `string`                         | A unique ID for this event.                                             |
| `integrationid` | `string`                         | The ID of the integration being fired.                                  |
| `type`          | `string` | The [observable event](#observable-events) that triggered this event. |
| `data`          | `object`                         | The resource affected by this event.                                    |

#### Example: Typical payload

The following example payload [observes](#observable-events) the `cart.updated` event. The configured queue receives the following message payload:
 
```javascript
{
 "data": {
   "description": "",
   "id": "a-cart-id",
   "links": {
     "self": "https://epcc-integration.global.ssl.fastly.net/v2/carts/a-cart-id"
   },
   "meta": {
     "display_price": {
       "discount": {
         "amount": 0,
         "currency": "USD",
         "formatted": "$0.00"
       },
       "tax": {
         "amount": 0,
         "currency": "USD",
         "formatted": "$0.00"
       },
       "with_tax": {
         "amount": 200,
         "currency": "USD",
         "formatted": "$2.00"
       },
       "without_tax": {
         "amount": 200,
         "currency": "USD",
         "formatted": "$2.00"
       }
     },
     "timestamps": {
       "created_at": "2021-05-17T11:30:07Z",
       "expires_at": "2021-05-24T11:31:08Z",
       "updated_at": "2021-05-17T11:31:08Z"
     }
   },
   "name": "Cart",
   "relationships": {
     "customers": {},
     "items": {
       "data": [
         {
           "id": "4d28bc2b-9db3-4c96-801b-df0ac5b41552",
           "type": "custom_item"
         }
       ]
     }
   },
   "type": "cart"
 },
 "datacontenttype": "application/json",
 "id": "9a21fb54-6c3b-432a-bade-82a60da6b59a",
 "integrationid": "e17db0d8-467b-4bf3-9c26-3dfe8b96e9d7",
 "source": "https://epcc-integration.global.ssl.fastly.net",
 "specversion": "1.0",
 "storeid": "b33e328f-31a8-4d57-b0a3-ebf1039b3756",
 "type": "cart.updated"
}
```

### Example: Deleted resources payload

When resources are deleted, and you observe an event, the resource delivered in the message only contains the resource type and ID.

```javascript
{
 "data": {
   "id": "a2733958-1273-4385-9a05-f1ca7684f760",
   "type": "product"
 },
 "datacontenttype": "application/json",
 "id": "efca76df-9fc1-4434-ba26-82339d9b723c",
 "integrationid": "e17db0d8-467b-4bf3-9c26-3dfe8b96e9d7",
 "source": "https://epcc-integration.global.ssl.fastly.net",
 "specversion": "1.0",
 "storeid": "b33e328f-31a8-4d57-b0a3-ebf1039b3756",
 "type": "product.deleted"
}
```
 
### Observable Events
 
You can pass multiple observable keys to the `observes` field of the [integration object](/docs/api/integrations/create-integration), or you can create individual events. You can use an array when you handle multiple webhooks at the same URL.

   
     
         Entity/Resource
         Action
         Observable Key
         Store/Organization
     
     
         Address
         Created
         <code>address.created</code>
         Store
     
     
         
         Updated
         <code>address.updated</code>
         Store
     
     
         
         Deleted
         <code>address.deleted</code>
         Store
     
     
         Account
         Created
         <code>account.created</code>
         Store
     
     
         
         Updated
         <code>account.updated</code>
         Store
     
     
         
         Deleted
         <code>account.deleted</code>
         Store
     
     
         Account Member
         Created
         <code>account-member.created</code>
         Store
     
     
         
         Updated
         <code>account-member.updated</code>
         Store
     
     
         
         Deleted
         <code>account-member.deleted</code>
         Store
     
     
         Account Membership
         Created
         <code>account-membership.created</code>
         Store
     
     
          
          Updated
          <code>account-membership.updated</code>
          Store
     
     
          
          Deleted
          <code>account-membership.deleted</code>
          Store
     
     
          Carts
          Updated
          <code>cart.updated</code>
          Store
     
     
          
          Deleted
          <code>cart.deleted</code>
          Store
     
     
          Currency
          Created
          <code>currency.created</code>
          Store
     
     
          
          Updated
          <code>currency.updated</code>
          Store
     
     
          
          Deleted
          <code>currency.deleted</code>
          Store
     
     
          Customer
          Created
          <code>customer.created</code>
          Store
     
     
          
          Updated
          <code>customer.updated</code>
          Store
     
     
          
          Deleted
          <code>customer.deleted</code>
          Store
     
     
          Custom API Entries
          Created
          <code>customAPIEntryType.created</code>
          Store
     
     
          
          Updated
          <code>customAPIEntryType.updated</code>
          Store
     
     
          
          Deleted
          <code>customAPIEntryType.deleted</code>
          Store
     
     
          File
          Created
          <code>file.created</code>
          Store
     
     
          
          Deleted
          <code>file.deleted</code>
          Store
     
     
          Integration (events)
          Created
          <code>integration.created</code>
          Store, Organization
     
     
          
          Updated
          <code>integration.updated</code>
          Store, Organization
     
     
          
          Deleted
          <code>integration.deleted</code>
          Store, Organization
     
     
          One-Time Password Token Request
          Created
          <code>one-time-password-token-request.created</code>
          Store
     
     
          Order Events
     
     
          Checkout
          Created
          <code>order.created</code>
          Store
     
     
          Payments
          Updated
          <code>order.updated</code> / <code>order.paid</code>. The event <code>order.paid</code> is triggered when the payment status is <code>paid</code>. The event <code>order.updated</code> is triggered when the order is captured, completed, refunded, anonymized, or updated.
          Store
     
     
          
          Authorized
          <code>order.authorized</code>
          Store
     
     
          Orders
          Fulfilled
          <code>order.fulfilled</code>
          Store
     
     
          
          Canceled
          <code>order.cancelled</code>
          Store
     
     
          Capture Transaction
          Paid
          <code>order.paid</code>. The event <code>order.paid</code> is triggered when the order status is completed and captured, and the payment status is <code>paid</code>.
          Store
     
     
          
          Captured
          <code>order.updated</code>. The event <code>order.updated</code> is triggered when the order is captured, completed, refunded, anonymized, or updated.
          Store
     
     
         Refund Transaction
          Refunded
          <code>order.refunded</code>
          Store
     
     
          Payment Gateway
          Updated
          <code>payment-gateway.updated</code>
          Store
     
     
          Catalog releases
          Created
          <code>catalog-release.created</code>
          Store, Organization
     
     
          
          Updated
          <code>catalog-release.updated</code>
          Store, Organization
     
     
          
          Deleted
          <code>catalog-release.deleted</code>
          Store, Organization
     
     
          Catalog rules
          Created
          <code>catalog-rule.created</code>
          Store
     
     
          
          Updated
          <code>catalog-rule.updated</code>
          Store
     
     
          
          Deleted
          <code>catalog-rule.deleted</code>
          Store
     
     
          Settings
          Created
          <code>settings.created</code>
          Store
     
     
          
          Updated
          <code>settings.updated</code>
          Store
     
     
          Stock Transaction
          Created
          <code>stock-transaction.created</code>
          Store
     
     
          Transaction
          Created
          <code>transaction.created</code>
          Store
     
     
          
          Updated
          <code>transaction.updated</code>
          Store
     
     
          Tax Items
          Updated
          <code>cart.updated</code>
          Store
     
     
          Subscriptions
          You can integrate Subscriptions with external systems like enterprise resource planning, fulfilment and other systems. For example, when a subscriber updates their address, the Customer Relationship Management system is updated with the change. See Subscriptions.
     
     
          User Authentication Info
          Created
          <code>user-authentication-info.created</code>
          Store
     
     
          
          Updated
          <code>user-authentication-info.updated</code>
          Store
     
     
          
          Deleted
          <code>user-authentication-info.deleted</code>
          Store
     
  

 
:::note
 
Store-level events contain `store_id` and `org_id` whereas, organization-level events contain only `org_id`.
 
:::

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Integrations

Setting up and managing integrations.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## List jobs for integration

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List jobs for integration"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/integrations/{integration_uuid}/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the jobs for the given integration UUID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"integration_uuid","in":"path","description":"The unique identifier of the integration.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. All integrations are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"id":{"description":"The ID of the integration job processed.","type":"string","example":"8848646b-2745-469e-8cc1-ee3b04738f8f"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `integration-job`.","enum":["integration-job"],"example":"integration-job"}},"title":"IntegrationJob"}}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":404,"detail":"The resource could not be found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## List logs for integration

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List logs for integration"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/integrations/{integration_uuid}/logs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the logs for the given integration UUID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"integration_uuid","in":"path","description":"The unique identifier of the integration.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns a list of integration logs.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"description":"As integrations can fail over time, Commerce provides the ability to browse all logs for your integrations.","properties":{"id":{"description":"A unique identifier of an integration whose logs you want to view.","type":"string","example":"ac8bb58e-2b9b-4ccf-9dd2-ecdf50417849"},"type":{"description":"This represents the type of resource object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"succeeded":{"type":"boolean","example":true,"description":"Whether the integration was successful."},"attempt":{"type":"integer","example":1,"description":"The number of attempts made to process the integration."},"body":{"type":"string","example":"Not Found","description":"The response returned from the integration."},"status_code":{"type":"integer","example":404,"description":"The status code returned from the integration."},"error_detail":{"type":"string","example":"Received a status code outside of 2xx range - treating webhook as a fail","description":"The reason why the integration failed."},"relationships":{"description":"Relationships are established between different integration entities. For example, a log and an integration job are related to an integration.","type":"object","properties":{"integration":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the integration processed.","example":"ff8634a8-a89e-4eac-baab-9b7b8c4f8720"},"type":{"type":"string","description":"This represents the resource type of the object being returned. Always `integration`.","example":"integration"}}}}},"job":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the integration job processed.","example":"ff8634a8-a89e-4eac-baab-9b7b8c4f8720"},"type":{"type":"string","description":"This represents the resource type of the object being returned. Always `integration-job`.","example":"job"}}}}}}}},"title":"IntegrationLog"}},"links":{"type":"object","description":"Links are used to allow you to move between pages.","properties":{"first":{"description":"Always the first page. This is not present on the first page.","type":"string","example":"/integrations/logs?page[offset]=0&page[limit]=10"},"next":{"description":"Next page link.","type":"string","example":"/integrations/logs?page[offset]=10&page[limit]=10"},"prev":{"description":"This is not present on the first page.","type":"string","example":"/integrations/logs?page[offset]=8&page[limit]=10"}},"title":"LogsPaginationLinks"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":404,"detail":"The resource could not be found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## List integrations

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List integrations"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/integrations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a list of all integrations created by the store.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. All integrations are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"properties":{"id":{"description":"The unique identifier of the integration.","type":"string","example":"2da46671-b4c2-44ac-b133-d1221aafc77b"},"type":{"description":"The type represents the object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"name":{"type":"string","example":"Order shipping notification","description":"The name of the integration."},"description":{"type":"string","example":"Send a shipping notification via email with discount code","description":"A description of what the integration is for."},"enabled":{"type":"boolean","example":true,"description":"Whether the integration is enabled."},"integration_type":{"type":"string","example":"webhook","description":"Specifies how the event is delivered. The options are `webhook`, `aws-sqs`, or `stomp`.","enum":["webhook","aws_sqs","stomp"],"default":"webhook"},"observes":{"description":"The list of events you want to observe. See [**Observable Events**](#observable-events).","type":"array","items":{"type":"string"}},"configuration":{"type":"object","oneOf":[{"required":["url","aws_access_key_id","aws_secret_access_key","region"],"properties":{"url":{"type":"string","format":"uri","example":"https://sqs.eu-west-1.amazonaws.com/123456789/epcc-external-queue","description":"The required SQS queue URL."},"aws_access_key_id":{"type":"string","example":"****************JIMB","description":"The required AWS access key ID."},"aws_secret_access_key":{"type":"string","example":"************************************HK4o","description":"The required AWS secret key ID."},"region":{"type":"string","example":"eu-west-1","description":"The required AWS region."}},"title":"AWSSQSConfigurationObject"},{"required":["url"],"properties":{"url":{"type":"string","example":"https://yourwebsite.com/order-created-notification","description":"A required URL that the integration fires.","format":"uri"},"secret_key":{"type":"string","example":"secret_key_to_validate_on_your_endpoint","description":"An optional header. Useful to authenticate the response came from Elastic Path. This is sent as `X-MOLTIN-SECRET-KEY`."}},"title":"WebhookConfigurationObject"},{"required":["url"],"properties":{"username":{"type":"string","example":"epcc-integration-1","description":"The username used to authenticate against a STOMP server."},"password":{"type":"string","example":"****************************CDKn","description":"The password used to authenticate against a STOMP server."},"destination":{"type":"string","example":"/queue/epcc-integrations.order-created","description":"The destination in the messaging queuing system."},"addresses":{"type":"array","items":{"type":"string","format":"uri"},"example":["stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-2.mq.us-west-2.amazonaws.com:61614","stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-1.mq.us-west-2.amazonaws.com:61614"],"description":"The addresses that correspond with the destination name."}},"title":"STOMPConfigurationObject"}]}},"title":"Integration"},{"type":"object","properties":{"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"?page[offset]=0&page[limit]=25","title":"LinkURI"}}}},"title":"Links"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"description":"The date and time a transaction is created.","properties":{"created_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"updated_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"Timestamps"}}}},"title":"Meta"}]}},"links":{"type":"object","description":"Links are used to allow you to move between pages.","properties":{"first":{"description":"Always the first page. This is not present on the first page.","type":"string","example":"/integrations?page[offset]=0&page[limit]=10"},"last":{"description":"This is not present if there is only one page.","type":"string","example":"/integrations?page[offset]=20&page[limit]=10"},"next":{"description":"This is not present if there is no next page.","type":"string","example":"/integrations?page[offset]=10&page[limit]=10"},"prev":{"description":"This is not present on the first page.","type":"string","example":"/integrations?page[offset]=8&page[limit]=10"}},"title":"PaginationLinks"},"results":{"description":"The results for this response for the entire collection.","type":"object","properties":{"total":{"description":"The total number of records for this response for the entire collection.","type":"integer","example":1}},"title":"Results"}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## List logs for the job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List logs for the job"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/integrations/{integration_uuid}/jobs/{job_uuid}/logs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the integration logs for the given integration and job UUID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"integration_uuid","in":"path","description":"The unique identifier of the integration.","required":true,"schema":{"type":"string"}},{"name":"job_uuid","in":"path","description":"The unique identifier of the integration job.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns a list of integration logs.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"description":"As integrations can fail over time, Commerce provides the ability to browse all logs for your integrations.","properties":{"id":{"description":"A unique identifier of an integration whose logs you want to view.","type":"string","example":"ac8bb58e-2b9b-4ccf-9dd2-ecdf50417849"},"type":{"description":"This represents the type of resource object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"succeeded":{"type":"boolean","example":true,"description":"Whether the integration was successful."},"attempt":{"type":"integer","example":1,"description":"The number of attempts made to process the integration."},"body":{"type":"string","example":"Not Found","description":"The response returned from the integration."},"status_code":{"type":"integer","example":404,"description":"The status code returned from the integration."},"error_detail":{"type":"string","example":"Received a status code outside of 2xx range - treating webhook as a fail","description":"The reason why the integration failed."},"relationships":{"description":"Relationships are established between different integration entities. For example, a log and an integration job are related to an integration.","type":"object","properties":{"integration":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the integration processed.","example":"ff8634a8-a89e-4eac-baab-9b7b8c4f8720"},"type":{"type":"string","description":"This represents the resource type of the object being returned. Always `integration`.","example":"integration"}}}}},"job":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the integration job processed.","example":"ff8634a8-a89e-4eac-baab-9b7b8c4f8720"},"type":{"type":"string","description":"This represents the resource type of the object being returned. Always `integration-job`.","example":"job"}}}}}}}},"title":"IntegrationLog"}},"links":{"type":"object","description":"Links are used to allow you to move between pages.","properties":{"first":{"description":"Always the first page. This is not present on the first page.","type":"string","example":"/integrations/logs?page[offset]=0&page[limit]=10"},"next":{"description":"Next page link.","type":"string","example":"/integrations/logs?page[offset]=10&page[limit]=10"},"prev":{"description":"This is not present on the first page.","type":"string","example":"/integrations/logs?page[offset]=8&page[limit]=10"}},"title":"LogsPaginationLinks"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":404,"detail":"The resource could not be found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## List logs for all integrations for the store

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List logs for all integrations for the store"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/integrations/logs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all integration logs for the store.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns a list of integration logs.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"description":"As integrations can fail over time, Commerce provides the ability to browse all logs for your integrations.","properties":{"id":{"description":"A unique identifier of an integration whose logs you want to view.","type":"string","example":"ac8bb58e-2b9b-4ccf-9dd2-ecdf50417849"},"type":{"description":"This represents the type of resource object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"succeeded":{"type":"boolean","example":true,"description":"Whether the integration was successful."},"attempt":{"type":"integer","example":1,"description":"The number of attempts made to process the integration."},"body":{"type":"string","example":"Not Found","description":"The response returned from the integration."},"status_code":{"type":"integer","example":404,"description":"The status code returned from the integration."},"error_detail":{"type":"string","example":"Received a status code outside of 2xx range - treating webhook as a fail","description":"The reason why the integration failed."},"relationships":{"description":"Relationships are established between different integration entities. For example, a log and an integration job are related to an integration.","type":"object","properties":{"integration":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the integration processed.","example":"ff8634a8-a89e-4eac-baab-9b7b8c4f8720"},"type":{"type":"string","description":"This represents the resource type of the object being returned. Always `integration`.","example":"integration"}}}}},"job":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the integration job processed.","example":"ff8634a8-a89e-4eac-baab-9b7b8c4f8720"},"type":{"type":"string","description":"This represents the resource type of the object being returned. Always `integration-job`.","example":"job"}}}}}}}},"title":"IntegrationLog"}},"links":{"type":"object","description":"Links are used to allow you to move between pages.","properties":{"first":{"description":"Always the first page. This is not present on the first page.","type":"string","example":"/integrations/logs?page[offset]=0&page[limit]=10"},"next":{"description":"Next page link.","type":"string","example":"/integrations/logs?page[offset]=10&page[limit]=10"},"prev":{"description":"This is not present on the first page.","type":"string","example":"/integrations/logs?page[offset]=8&page[limit]=10"}},"title":"LogsPaginationLinks"}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an integration

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an integration"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/integrations/{integration_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates the Integration for the given UUID. Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the integration is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"integration_uuid","in":"path","description":"The unique identifier of the integration.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type"],"properties":{"type":{"description":"The type represents the object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"name":{"type":"string","example":"Order shipping notification","description":"The name of the integration."},"description":{"type":"string","example":"Send a shipping notification via email with discount code","description":"A description of what the integration is for."},"enabled":{"type":"boolean","example":true,"description":"Whether the integration is enabled."},"integration_type":{"type":"string","example":"webhook","enum":["webhook","aws_sqs","stomp"],"default":"webhook"},"observes":{"type":"array","description":"The list of events you want to observe. See [**Observable Events**](#observable-events).","items":{"type":"string"}},"configuration":{"description":"The content of the configuration object depends on the value of `integration_type`.","type":"object","oneOf":[{"required":["url","aws_access_key_id","aws_secret_access_key","region"],"properties":{"url":{"type":"string","format":"uri","example":"https://sqs.eu-west-1.amazonaws.com/123456789/epcc-external-queue","description":"The required SQS queue URL."},"aws_access_key_id":{"type":"string","example":"****************JIMB","description":"The required AWS access key ID."},"aws_secret_access_key":{"type":"string","example":"************************************HK4o","description":"The required AWS secret key ID."},"region":{"type":"string","example":"eu-west-1","description":"The required AWS region."}},"title":"AWSSQSConfigurationObject"},{"required":["url"],"properties":{"url":{"type":"string","example":"https://yourwebsite.com/order-created-notification","description":"A required URL that the integration fires.","format":"uri"},"secret_key":{"type":"string","example":"secret_key_to_validate_on_your_endpoint","description":"An optional header. Useful to authenticate the response came from Elastic Path. This is sent as `X-MOLTIN-SECRET-KEY`."}},"title":"WebhookConfigurationObject"},{"required":["url"],"properties":{"username":{"type":"string","example":"epcc-integration-1","description":"The username used to authenticate against a STOMP server."},"password":{"type":"string","example":"****************************CDKn","description":"The password used to authenticate against a STOMP server."},"destination":{"type":"string","example":"/queue/epcc-integrations.order-created","description":"The destination in the messaging queuing system."},"addresses":{"type":"array","items":{"type":"string","format":"uri"},"example":["stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-2.mq.us-west-2.amazonaws.com:61614","stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-1.mq.us-west-2.amazonaws.com:61614"],"description":"The addresses that correspond with the destination name."}},"title":"STOMPConfigurationObject"}]}},"title":"IntegrationUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. All integrations are returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"properties":{"id":{"description":"The unique identifier of the integration.","type":"string","example":"2da46671-b4c2-44ac-b133-d1221aafc77b"},"type":{"description":"The type represents the object being returned. Always `integration`.","type":"string","example":"integration","enum":["integration"],"default":"integration"},"name":{"type":"string","example":"Order shipping notification","description":"The name of the integration."},"description":{"type":"string","example":"Send a shipping notification via email with discount code","description":"A description of what the integration is for."},"enabled":{"type":"boolean","example":true,"description":"Whether the integration is enabled."},"integration_type":{"type":"string","example":"webhook","description":"Specifies how the event is delivered. The options are `webhook`, `aws-sqs`, or `stomp`.","enum":["webhook","aws_sqs","stomp"],"default":"webhook"},"observes":{"description":"The list of events you want to observe. See [**Observable Events**](#observable-events).","type":"array","items":{"type":"string"}},"configuration":{"type":"object","oneOf":[{"required":["url","aws_access_key_id","aws_secret_access_key","region"],"properties":{"url":{"type":"string","format":"uri","example":"https://sqs.eu-west-1.amazonaws.com/123456789/epcc-external-queue","description":"The required SQS queue URL."},"aws_access_key_id":{"type":"string","example":"****************JIMB","description":"The required AWS access key ID."},"aws_secret_access_key":{"type":"string","example":"************************************HK4o","description":"The required AWS secret key ID."},"region":{"type":"string","example":"eu-west-1","description":"The required AWS region."}},"title":"AWSSQSConfigurationObject"},{"required":["url"],"properties":{"url":{"type":"string","example":"https://yourwebsite.com/order-created-notification","description":"A required URL that the integration fires.","format":"uri"},"secret_key":{"type":"string","example":"secret_key_to_validate_on_your_endpoint","description":"An optional header. Useful to authenticate the response came from Elastic Path. This is sent as `X-MOLTIN-SECRET-KEY`."}},"title":"WebhookConfigurationObject"},{"required":["url"],"properties":{"username":{"type":"string","example":"epcc-integration-1","description":"The username used to authenticate against a STOMP server."},"password":{"type":"string","example":"****************************CDKn","description":"The password used to authenticate against a STOMP server."},"destination":{"type":"string","example":"/queue/epcc-integrations.order-created","description":"The destination in the messaging queuing system."},"addresses":{"type":"array","items":{"type":"string","format":"uri"},"example":["stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-2.mq.us-west-2.amazonaws.com:61614","stomp+ssl://b-618354a5-e04f-4eff-99c7-734e9d8b91a5-1.mq.us-west-2.amazonaws.com:61614"],"description":"The addresses that correspond with the destination name."}},"title":"STOMPConfigurationObject"}]}},"title":"Integration"},{"type":"object","properties":{"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"?page[offset]=0&page[limit]=25","title":"LinkURI"}}}},"title":"Links"},{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"description":"The date and time a transaction is created.","properties":{"created_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"updated_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"Timestamps"}}}},"title":"Meta"}]},"links":{"type":"object","properties":{"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"?page[offset]=0&page[limit]=25","title":"LinkURI"}}}},"title":"Links"},"meta":{"type":"object","properties":{"meta":{"type":"object","properties":{"timestamps":{"description":"The date and time a transaction is created.","properties":{"created_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"updated_at":{"description":"The date and time an integration is updated.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"Timestamps"}}}},"title":"Meta"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":404,"detail":"The resource could not be found"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":400,"detail":"Your request was invalid"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."}},"title":"ErrorBody"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":500}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a Merchant Realm Mapping

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Merchant Realm Mapping"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/merchant-realm-mappings/{mapping_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a Merchant Realm Mapping

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"mapping_id","in":"path","required":true,"description":"The id of the Application Key.","schema":{"type":"string","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for this merchant realm mapping.","format":"uuid","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0"},"prefix":{"type":"string","description":"The store prefix that is assigned to this merchant realm mapping. This can be `null` if a store prefix has not been assigned.","example":"myCompany"},"type":{"type":"string","description":"Represents the type of object being returned. Always `merchant-realm-mappings`.","const":"merchant-realm-mappings"},"realm_id":{"type":"string","description":"The ID of the authentication realm used to sign in as administrator.","example":"e730bf37-ed95-4ca9-b4c4-2c5ee08b21d7"},"store_id":{"type":"string","description":"System-generated store ID.","example":"88888888-4444-4333-8333-111111111111"}},"title":"MerchantRealmMappingResponse"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"merchant realm mapping not found\",\n      \"status\": \"404\",\n      \"title\": \"Not Found\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get the Merchant Realm Mapping for the current store

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get the Merchant Realm Mapping for the current store"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/merchant-realm-mappings"}
  context={"endpoint"}
>
  
</MethodEndpoint>

This API is used to obtain an [Authentication Realm](/docs/api/single-sign-on/authentication-realms) if there is none yet for the current store.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for this merchant realm mapping.","format":"uuid","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0"},"prefix":{"type":"string","description":"The store prefix that is assigned to this merchant realm mapping. This can be `null` if a store prefix has not been assigned.","example":"myCompany"},"type":{"type":"string","description":"Represents the type of object being returned. Always `merchant-realm-mappings`.","const":"merchant-realm-mappings"},"realm_id":{"type":"string","description":"The ID of the authentication realm used to sign in as administrator.","example":"e730bf37-ed95-4ca9-b4c4-2c5ee08b21d7"},"store_id":{"type":"string","description":"System-generated store ID.","example":"88888888-4444-4333-8333-111111111111"}},"title":"MerchantRealmMappingResponse"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":"{\n  \"errors\": [\n    {\n      \"title\": \"Unauthorized\",\n      \"status\": \"401\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Merchant Realm Mappings Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/merchant-realm-mappings/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Merchant Realm Mappings Introduction"}
>
</Heading>

The Merchant Realm Mapping object is used to locate the [Authentication Realm](/docs/api/single-sign-on/authentication-realms) which administrators use to sign in to a store via single sign-on. When supplied in the mapping, the prefix field is used during authentication to determine the appropriate authentication realm to sign in with.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Update a Merchant Realm Mapping

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Merchant Realm Mapping"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/merchant-realm-mappings/{mapping_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a Merchant Realm Mapping

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"mapping_id","in":"path","required":true,"description":"The id of the Application Key.","schema":{"type":"string","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"required":["data"],"properties":{"data":{"required":["type","prefix"],"properties":{"prefix":{"type":"string","description":"The store prefix that is assigned to this merchant realm mapping. This can be `null` if a store prefix has not been assigned.","example":"myCompany"},"type":{"type":"string","description":"Represents the type of object being returned. Always `merchant-realm-mappings`.","const":"merchant-realm-mappings"}},"title":"MerchantRealmMapping"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for this merchant realm mapping.","format":"uuid","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0"},"prefix":{"type":"string","description":"The store prefix that is assigned to this merchant realm mapping. This can be `null` if a store prefix has not been assigned.","example":"myCompany"},"type":{"type":"string","description":"Represents the type of object being returned. Always `merchant-realm-mappings`.","const":"merchant-realm-mappings"},"realm_id":{"type":"string","description":"The ID of the authentication realm used to sign in as administrator.","example":"e730bf37-ed95-4ca9-b4c4-2c5ee08b21d7"},"store_id":{"type":"string","description":"System-generated store ID.","example":"88888888-4444-4333-8333-111111111111"}},"title":"MerchantRealmMappingResponse"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"The field 'prefix' is required.\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"merchant realm mapping not found\",\n      \"status\": \"404\",\n      \"title\": \"Not Found\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"conflict-error":{"summary":"Prefix already in use","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"the prefix is already in use\",\n      \"status\": \"409\",\n      \"title\": \"Conflict\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Gateways

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Get a Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Gateway"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/gateways/{gatewaySlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the specified gateway.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"gatewaySlug","in":"path","description":"The slug of the gateway.","required":true,"schema":{"type":"string","enum":["manual","braintree","stripe","stripe_payment_intents","elastic_path_payments_stripe","paypal_express_checkout","adyen","authorize_net","card_connect","cyber_source"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"login":{"description":"Represents your login ID.","type":"string"},"name":{"description":"Represents the name of the gateway.","example":"{gatewayName}","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"},"password":{"description":"Specifies your password.","type":"string"},"signature":{"type":"string"},"slug":{"description":"Specifies the slug of the gateway.","example":"{gatewaySlug}","type":"string"},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","example":false,"type":"boolean"}},"title":"Response.Gateway"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Get all Gateways

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Gateways"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/gateways"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all gateways.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"array","items":{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"login":{"description":"Represents your login ID.","type":"string"},"name":{"description":"Represents the name of the gateway.","example":"{gatewayName}","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"},"password":{"description":"Specifies your password.","type":"string"},"signature":{"type":"string"},"slug":{"description":"Specifies the slug of the gateway.","example":"{gatewaySlug}","type":"string"},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","example":false,"type":"boolean"}},"title":"Response.Gateway"}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Payment Gateways Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/payments/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Payment Gateways Introduction"}
>
</Heading>

Payments for orders are processed through a payment gateway. Composable Commerce offers integrations for a selection of payment gateway providers, or you can create your own integrations.

Payment transactions are processed similarly for all gateways:

1. A payment transaction is created and an attempt to pay is made.
2. The transaction is forwarded to the third-party gateway specified by the customer.
3. The payment is processed by the third-party gateway.

Payment transactions are always processed outside of Composable Commerce for security reasons. Typically, you use a token rather than pass the card details directly. If, however, you want to pass the cart details directly to the third-party provider, Composable Commerce enforces the use of the secure HTTPS protocol. If the transaction is successful, a `200 OK` response is returned. Use the response (success or failure) to update the transaction, which automatically updates the order and payment statuses.

A payment transaction can also be refunded. You can select which way you want to process refunds:

- Mark as Refunded: You can use your payment gateway’s console to process a refund. Process the refund first in the payment gateway and then use the **Mark as Refunded** capability in Composable Commerce to complete the process.
- Refund through Composable Commerce: Start a full or partial refund to a supported payment provider directly from Commerce Manager or the API. You still have the ability to mark as refunded for a pre-integrated gateway, such as Stripe.

:::info

For nonce-based Authorize.net transactions, if a refund is requested before the transaction has settled (typically within 24 hours), the transaction will be voided instead of refunded. This behavior is specific to nonce-based payments.

:::

:::caution

Configure your store to use [Manual Gateway](/docs/api/payments/update-manual-gateway) to process payments if the order total is zero or the payment is through non-supported payment providers.

:::

### Order Status Workflow

The following image shows the workflow of the order status when you checkout a cart.

![Order Workflow](/assets/Order-Workflow.png)

### Summary of the Workflow

1. [Checkout a cart](/docs/api/carts/checkout). When you checkout a cart, an unpaid order is returned.
2. [Paying for an order](/docs/api/carts/payments). You can process the payment for an order through a payment gateway. You can pay for an order either using purchase payment method or authorize payment method.
3. Confirm the order. Order confirmation might be required when you purchase or authorize a transaction. If you use a purchase method, the order is immediately confirmed. If you use authorize method, funds are captured later when an item is dispatched or restocked, and then the order is considered as complete. See [Capture a Transaction](https://elasticpath.dev/docs/commerce-cloud/payments/transactions/capture-a-transaction).
4. [Fulfill, Refund or Cancel the paid order](/docs/api/carts/refund-a-transaction). The order is considered as fulfilled when it is shipped. You can cancel the order after the checkout or if the order is not fulfilled. You can also choose to refund a partial payment or full payment.
5. (Optional) [Cancel a transaction](/docs/api/carts/cancel-a-transaction). You can cancel or void a pending or authorized transaction. The transaction can be canceled or voided when it is in pending and completed statuses. This works only for Stripe and PayPal and does not work for manual gateway.
6. (Optional) [Anonymize an order](/docs/api/carts/anonymize-orders). You can anonymize an order when it is fulfilled, canceled, or fully refunded.

### Split Payments

Split payments involve multiple payment sources for a single order, using externally authorized payments. For example, you can pay for an order using a gift card and a credit card. An order with multiple payment transactions can also be in multiple payment states depending on each transaction.

Transactions for split payments are processed similarly for all gateways:

1. A partial payment transaction is created and an attempt to pay the partial amount is made.
2. The transaction for the specified amount is forwarded to the payment gateway specified by the customer.
3. The partial payment is processed.
4. Another partial payment transaction is created and an attempt to pay the remaining amount is made.
5. Another transaction for the remaining amount is forwarded to the payment gateway specified by the customer.
6. The payment is processed, paid, and complete. The payment status must show paid after the order is completed.

You can refund transactions for split payments. For more information about refund, see Refund a Payment.

The following scenarios show how a shopper can use multiple sources for split payment:

- Gift card and credit card
- Purchase order and credit card
- Store credit and credit card
- Employee dollars and credit card
- Gift card and loyalty card
- Loyalty card and wallet

The following image shows a workflow of the split payments.

![Split Payments](/assets/split-payment-workflow.png)

The following table describes the payment and order statuses that you can see when an order is passed through multiple stages.

| Payment Status   | Order Status | Inventory Status     | Description |
|:-----------------|:-------------|:---------------------|:------------|
| `partially_authorized` | `incomplete` |	Allocated	| Indicates that the payment is partially_authorized and the balance_owing value is greater than zero. In this case, one of the transactions is authorized and complete. |
| `partially_paid`  | `incomplete` |Allocated |	Indicates that the funds are captured but the balance_owing value is greater than zero. In this case, one of the transactions is captured or purchase is complete. |
| `unpaid` | `incomplete` |	Not Allocated |	Indicates that the order does not have any complete payment transactions. In this case, all the transactions or any of the transactions can be still pending. |
| `authorized`	| `processing`	| Allocated | 	Indicates that completed transactions cover the entire total amount for an order and at least one of the transactions is authorized. |
| `paid` |	`complete`	| Allocated | Indicates that the order is complete and the amount for the order is fully paid when all authorized transactions are captured or purchase transactions are complete. |

  
    Contact
  
    Elastic Path: 
  
    URL: [https://elasticpath.com](https://elasticpath.com)

---

## Update Adyen Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Adyen Gateway"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/adyen"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure Adyen.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"title":"Update Adyen Gateway Request","type":"object","properties":{"data":{"title":"Update Adyen Gateway Data","type":"object","required":["merchant_account","username","password"],"properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[true]},"merchant_account":{"description":"Represents your Adyen merchant account code. For example, MyCompanyECOM.","type":"string"},"username":{"description":"Indicates your web service username. For example, ws@Company.MyCompany.","type":"string"},"password":{"description":"Specifies your web service user Basic Auth password.","type":"string"},"test":{"description":"Specifies whether the test account is enabled or disabled. Set `true` to enable the test account and `false` to disable the test account. Default is `false`.","type":"boolean","examples":[false]}}}}},"examples":{"default":{"value":{"data":{"enabled":true,"merchant_account":"MyCompanyECOM","username":"ws@Company.MyCompany","password":"xxx","test":false}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","allOf":[{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"login":{"description":"Represents your login ID.","type":"string"},"name":{"description":"Represents the name of the gateway.","example":"{gatewayName}","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"},"password":{"description":"Specifies your password.","type":"string"},"signature":{"type":"string"},"slug":{"description":"Specifies the slug of the gateway.","example":"{gatewaySlug}","type":"string"},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","example":false,"type":"boolean"}},"title":"Response.Gateway"},{"properties":{"merchant_account":{"description":"Represents your Adyen merchant account code. For example, MyCompanyECOM.","type":"string","example":"MyCompanyECOM"}}}]}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update Authorize.net Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Authorize.net Gateway"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/authorize_net"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure Authorize.net.

:::note
The credentials used for a test account may differ from those used for a live account. When configuring the payment gateway with your credentials and setting `test` to `true`, the system allows you to test various Authorize.net payment interactions to ensure everything works as expected. Once you are ready to go live, update `test` as `false` to direct requests to the live endpoints instead of the test account. Additionally, ensure that you switch to the credentials for the live account when making this change. To access your sandbox environment, see [Authorize.net Sandbox account](https://developer.authorize.net/hello_world/sandbox.html).
:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Update Authorize Net Gateway Request","type":"object","properties":{"data":{"title":"Update Authorize Net Gateway Data","type":"object","required":["login","password"],"properties":{"login":{"description":"Represents Authorize.net API Login ID.","type":"string"},"password":{"description":"Indicates Authorize.net Transaction Key.","type":"string"},"slug":{"description":"Specifies a unique slug for this gateway.","type":"string"},"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[true]},"test":{"description":"Specifies whether the test account is enabled or disabled. Set `true` to enable the test account and `false` to disable the test account. Default is `false`.","type":"boolean","examples":[true]}}}}}]},"examples":{"default":{"value":{"data":{"login":"xxx","password":"xxx","slug":"authorize_net","enabled":true,"test":true}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","allOf":[{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"login":{"description":"Represents your login ID.","type":"string"},"name":{"description":"Represents the name of the gateway.","example":"{gatewayName}","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"},"password":{"description":"Specifies your password.","type":"string"},"signature":{"type":"string"},"slug":{"description":"Specifies the slug of the gateway.","example":"{gatewaySlug}","type":"string"},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","example":false,"type":"boolean"}},"title":"Response.Gateway"},{"properties":{"password":{"description":"Indicates Authorize.net Transaction Key.","type":"string","example":"authorize-net-transaction-key"}}}]}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update Braintree Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Braintree Gateway"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/braintree"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure Braintree.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Update Braintree Gateway Request","type":"object","properties":{"data":{"title":"Update Braintree Gateway Data","type":"object","required":["merchant_id","private_key","public_key"],"properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[true]},"environment":{"description":"Specifies production or sandbox environment.","type":"string","examples":["sandbox"]},"merchant_id":{"description":"Specifies Your Braintree merchant ID.","type":"string","examples":["{{braintreeMerchantId}}"]},"private_key":{"description":"Represents Your Braintree private key.","type":"string","examples":["{{braintreePrivateKey}}"]},"public_key":{"description":"Indicates Your Braintree public key.","type":"string","examples":["{{braintreePublicKey}}"]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"enabled":true,"environment":"sandbox","merchant_id":"{{braintreeMerchantId}}","private_key":"{{braintreePrivateKey}}","public_key":"{{braintreePublicKey}}"}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"name":{"description":"Specifies the name of the gateway.","example":"Braintree","type":"string"},"environment":{"description":"Specifies production or sandbox environment.","example":"sandbox","type":"string"},"merchant_id":{"description":"Specifies Your Braintree merchant ID.","example":"{{braintreeMerchantId}}","type":"string"},"private_key":{"description":"Represents Your Braintree private key.","example":"{{braintreePrivateKey}}","type":"string"},"public_key":{"description":"Indicates Your Braintree public key.","example":"{{braintreePublicKey}}","type":"string"},"slug":{"description":"Represents the slug of the gateway.","example":"braintree","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update CardConnect Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update CardConnect Gateway"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/card_connect"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure CardConnect.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"title":"Update CardConnect Gateway Request","type":"object","properties":{"data":{"title":"Update CardConnect Gateway Data","type":"object","required":["merchant_id","username","password"],"properties":{"merchant_id":{"description":"Specifies your CardConnect Merchant ID.","type":"string"},"username":{"description":"Represents your CardConnect username.","type":"string"},"password":{"description":"Indicates your CardConnect password.","type":"string"},"test":{"description":"Specifies whether the test account is enabled or disabled. Set `true` to enable the test account and `false` to disable the test account. Default is `false`.","type":"boolean","examples":[false]},"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[false]}}}}},"examples":{"default":{"value":{"data":{"merchant_id":"xxx","username":"xxx","password":"xxx","test":false,"enabled":false}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","allOf":[{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"login":{"description":"Represents your login ID.","type":"string"},"name":{"description":"Represents the name of the gateway.","example":"{gatewayName}","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"},"password":{"description":"Specifies your password.","type":"string"},"signature":{"type":"string"},"slug":{"description":"Specifies the slug of the gateway.","example":"{gatewaySlug}","type":"string"},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","example":false,"type":"boolean"}},"title":"Response.Gateway"},{"properties":{"merchant_id":{"description":"Specifies your CardConnect Merchant ID.","type":"string"}}}]}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update CyberSource Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update CyberSource Gateway"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/cyber_source"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure CyberSource.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"title":"Update CyberSource Gateway Request","type":"object","properties":{"data":{"title":"Update CyberSource Gateway Data","type":"object","required":["login","password"],"properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[true]},"test":{"description":"Specifies whether the test account is enabled or disabled. Set `true` to enable the test account and `false` to disable the test account. Default is `false`.","type":"boolean","examples":[true]},"login":{"description":"Represents your live or test CyberSource merchant ID.","type":"string"},"password":{"description":"Indicates your live or test CyberSource SOAP key.","type":"string"}}}}},"examples":{"default":{"value":{"data":{"enabled":true,"login":"xxx","password":"xxx","test":true}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","allOf":[{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"login":{"description":"Represents your login ID.","type":"string"},"name":{"description":"Represents the name of the gateway.","example":"{gatewayName}","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"},"password":{"description":"Specifies your password.","type":"string"},"signature":{"type":"string"},"slug":{"description":"Specifies the slug of the gateway.","example":"{gatewaySlug}","type":"string"},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","example":false,"type":"boolean"}},"title":"Response.Gateway"},{"properties":{"login":{"description":"Represents your live or test CyberSource merchant ID.","type":"string","example":"cybersource-merchant-id"},"password":{"description":"Indicates your live or test CyberSource SOAP key.","type":"string","example":"cybersource SOAP key"}}}]}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update Elastic Path Payments Powered by Stripe

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Elastic Path Payments Powered by Stripe"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/elastic_path_payments_stripe"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure Elastic Path Payments Powered by Stripe in Commerce. 

:::note

You can contact Elastic Path sales or [customer success team](mailto:customersuccess@elasticpath.com) to get more information about Elastic Path Payments Powered by Stripe and to check whether it will work for you.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Update Elastic Path Payments by Stripe Gateway Request","type":"object","properties":{"data":{"title":"Update Elastic Path Payments by Stripe Gateway Data","type":"object","required":["stripe_account"],"properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[true]},"stripe_account":{"description":"Specifies the Stripe account ID.","type":"string","examples":["{{stripeAccountId}}"]},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","type":"boolean","examples":[true]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"enabled":true,"stripe_account":"{{stripeAccountId}}","test":true}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"stripe_account":{"description":"Specifies the Stripe account ID.","example":"{{stripeAccountId}}","type":"string"},"name":{"description":"Specifies the name of the gateway.","example":"Elastic Path Payments powered by Stripe","type":"string"},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","example":true,"type":"boolean"},"slug":{"description":"Represents the slug of the gateway.","example":"elastic_path_payments_stripe","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update Manual Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Manual Gateway"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/manual"}
  context={"endpoint"}
>
  
</MethodEndpoint>

This endpoint allows you update the manual gateway.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"oneOf":[{"title":"Update Manual Gateway Request","type":"object","properties":{"data":{"title":"Update Manual Gateway Data","type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":true}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"enabled":true}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"name":{"description":"Specifies the nme of the gateway.","example":"Manual","type":"string"},"slug":{"description":"Specifies the slug of the gateway.","example":"manual","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update PayPal Express Checkout

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update PayPal Express Checkout"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/paypal_express_checkout"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure PayPal Express Checkout. 
:::note

To learn more about PayPal Express Checkout and check whether it will work for you, contact your sales or [customer success team](mailto:customersuccess@elasticpath.com).

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Update Paypal Express Checkout Gateway Request","type":"object","properties":{"data":{"title":"Update Paypal Express Checkout Gateway Data","type":"object","required":["payer_id"],"properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[true]},"payer_id":{"description":"Specifies the merchant account ID. The ID is displayed in the PayPal account details of the merchant.","type":"string","examples":["{{merchant account id}}"]},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","type":"boolean","examples":[true]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"enabled":true,"payer_id":"{{merchant account id}}","test":true}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"payer_id":{"description":"Specifies the merchant account ID. The ID is displayed in the PayPal account details of the merchant.","example":"{{merchant account id}}","type":"string"},"name":{"description":"Specifies the name of the gateway.","example":"PayPal Express Checkout","type":"string"},"test":{"description":"Specifies whether the test mode is enabled. Set `true` to enable test mode and `false` to disable the test mode. Default is `false`.","example":true,"type":"boolean"},"slug":{"description":"Represents the slug of the gateway.","example":"paypal_express_checkout","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update Stripe Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Stripe Gateway"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/stripe"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure Stripe.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Update Stripe Gateway Request","type":"object","properties":{"data":{"title":"Update Stripe Gateway Data","type":"object","required":["login"],"properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[true]},"login":{"description":"Represents Stripe `test` or `live` secret key.","type":"string","examples":["{{stripeToken}}"]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"enabled":true,"login":"{{stripeToken}}"}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"login":{"description":"Represents Stripe test or live secret key.","example":"{{stripeToken}}","type":"string"},"name":{"description":"Specifies the name of the gateway.","example":"Stripe","type":"string"},"slug":{"description":"Represents the slug of the gateway.","example":"stripe","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Update Stripe Payment Intents Gateway

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Stripe Payment Intents Gateway"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/gateways/stripe_payment_intents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to configure Stripe Payment Intents.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Update Stripe Gateway Request","type":"object","properties":{"data":{"title":"Update Stripe Gateway Data","type":"object","required":["login"],"properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","type":"boolean","examples":[true]},"login":{"description":"Represents Stripe `test` or `live` secret key.","type":"string","examples":["{{stripeToken}}"]}}}}}],"contentMediaType":"application/json"},"examples":{"default":{"value":{"data":{"enabled":true,"login":"{{stripeLoginToken}}"}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"enabled":{"description":"Specifies whether the gateway is enabled or disabled. Set `true` to enable the gateway and `false` to disable the gateway. Default is `false`.","example":true,"type":"boolean"},"login":{"description":"Specifies the Stripe secret key for your account that is in live or test mode.","example":"{{stripeLoginToken}}","type":"string"},"name":{"description":"Specifies the name of the gateway.","example":"Stripe Payment Intents","type":"string"},"slug":{"description":"Represents the slug of the gateway.","example":"stripe_payment_intents","type":"string"},"type":{"description":"Specifies the type of object being returned.","example":"gateway","type":"string"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":{"errors":{"status":401,"title":"Unauthorized"}}}}}}}
>
  
</StatusCodes>

---

## Create A Custom API Role Policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create A Custom API Role Policy"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/permissions/custom-api-role-policies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create A Custom API Role Policy

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","create","list","read","update","delete","relationships"],"properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.","const":"custom_api_role_policy"},"create":{"type":"boolean","description":"Specifies if the Role can create a Custom API Entry."},"list":{"type":"boolean","description":"Specifies if the Role can retrieve a list of Custom API Entries."},"read":{"type":"boolean","description":"Specifies if the Role can get a Custom API Entry."},"update":{"type":"boolean","description":"Specifies if the Role can update a Custom API Entry."},"delete":{"type":"boolean","description":"Specifies if the Role can delete a Custom API Entry."},"relationships":{"type":"object","properties":{"custom_api":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API.","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of the resource object.","const":"custom_api"}}}}},"role":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Role.","example":"it-developer"},"type":{"type":"string","description":"Specifies the type of the resource object.","enum":["standard_user_role","standard_shopper_role"]}}}}}},"title":"CustomAPIRolePolicyRelationships"}}}}},"examples":{"Create Example":{"summary":"Create a Custom API Role Policy","value":{"data":{"type":"custom_api_role_policy","create":true,"list":false,"read":true,"update":false,"delete":true,"relationships":{"custom_api":{"data":{"id":"fded1d2a-8bb8-48b6-86a5-9eb05cc8626a","type":"custom_api"}},"role":{"data":{"id":"it-developer","type":"standard_user_role"}}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"A Custom API Role Policy","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Role Policy.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.","const":"custom_api_role_policy"},"create":{"type":"boolean","description":"Specifies if the Role can create a Custom API Entry."},"list":{"type":"boolean","description":"Specifies if the Role can retrieve a list of Custom API Entries."},"read":{"type":"boolean","description":"Specifies if the Role can get a Custom API Entry."},"update":{"type":"boolean","description":"Specifies if the Role can update a Custom API Entry."},"delete":{"type":"boolean","description":"Specifies if the Role can delete a Custom API Entry."},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Role Policy.","example":"/v2/permissions/custom-api-role-policies/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},"relationships":{"type":"object","properties":{"custom_api":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API.","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of the resource object.","const":"custom_api"}}}}},"role":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Role.","example":"it-developer"},"type":{"type":"string","description":"Specifies the type of the resource object.","enum":["standard_user_role","standard_shopper_role"]}}}}}},"title":"CustomAPIRolePolicyRelationships"}},"title":"CustomAPIRolePolicy"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"409":{"description":"Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"duplicate-custom-api":{"summary":"Duplicate Custom API","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_api with the given api_type already exists\"\n    }\n  ]\n}\n"},"duplicate-custom-field":{"summary":"Duplicate Custom Field","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Conflict\",\n      \"status\": \"409\",\n      \"detail\": \"custom_field with the given slug already exists\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Custom API Role Policies

A Custom API Role Policy defines the level of access a role has to a Custom API. By default, administrative roles like **Store Admin** or **Org Admin** have full access to all Custom APIs. To grant access to other roles, a policy must be created for that specific role and Custom API.

Below are the permissions that can be assigned to a role:

| Permission | Description                              |
|------------|------------------------------------------|
| **Create** | Create a Custom API Entry.               |
| **List**   | Retrieve a list of Custom API Entries.   |
| **Read**   | Get a Custom API Entry.                  |
| **Update** | Update a Custom API Entry.               |
| **Delete** | Delete a Custom API Entry.               |

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Delete a Custom API Role Policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Custom API Role Policy"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/permissions/custom-api-role-policies/{custom-api-role-policy-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete A Custom API Role Policy

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-role-policy-id","description":"The ID of the Custom API Role Policy.","in":"path","required":true,"schema":{"type":"string"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"not-found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get a Custom API Role Policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Custom API Role Policy"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/permissions/custom-api-role-policies/{custom-api-role-policy-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get A Custom API Role Policy

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-role-policy-id","description":"The ID of the Custom API Role Policy.","in":"path","required":true,"schema":{"type":"string"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Custom API Role Policy","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Role Policy.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.","const":"custom_api_role_policy"},"create":{"type":"boolean","description":"Specifies if the Role can create a Custom API Entry."},"list":{"type":"boolean","description":"Specifies if the Role can retrieve a list of Custom API Entries."},"read":{"type":"boolean","description":"Specifies if the Role can get a Custom API Entry."},"update":{"type":"boolean","description":"Specifies if the Role can update a Custom API Entry."},"delete":{"type":"boolean","description":"Specifies if the Role can delete a Custom API Entry."},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Role Policy.","example":"/v2/permissions/custom-api-role-policies/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},"relationships":{"type":"object","properties":{"custom_api":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API.","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of the resource object.","const":"custom_api"}}}}},"role":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Role.","example":"it-developer"},"type":{"type":"string","description":"Specifies the type of the resource object.","enum":["standard_user_role","standard_shopper_role"]}}}}}},"title":"CustomAPIRolePolicyRelationships"}},"title":"CustomAPIRolePolicy"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"not-found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get a Standard Shopper Role

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Standard Shopper Role"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/permissions/standard-shopper-roles/{standard-shopper-role-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a Standard Shopper Role

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"standard-shopper-role-id","description":"The ID of the Standard Shopper Role.","in":"path","required":true,"schema":{"type":"string"},"example":"guest-shopper"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Standard Shopper Role","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Standard Shopper Role."},"type":{"type":"string","description":"Specifies the type of the resource object, use `standard_shopper_role` for Standard Shopper Roles.","const":"standard_shopper_role"},"name":{"type":"string","description":"Specifies the name of the Standard Shopper Role."},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Standard Shopper Role.","example":"/v2/permissions/standard-shopper-roles/guest-shopper","type":["string","null"],"format":"uri","title":"LinkURI"}}}},"title":"StandardShopperRole"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"not-found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get a Standard User Role

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Standard User Role"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/permissions/standard-user-roles/{standard-user-role-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a Standard User Role

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"standard-user-role-id","description":"The ID of the Standard User Role.","in":"path","required":true,"schema":{"type":"string"},"example":"it-developer"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Standard User Role","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Standard User Role."},"type":{"type":"string","description":"Specifies the type of the resource object, use `standard_user_role` for Standard User Roles.","const":"standard_user_role"},"name":{"type":"string","description":"Specifies the name of the Standard User Role."},"access_levels":{"type":"object","description":"Specifies the access levels for each permission group.","properties":{"accounts":{"type":"string","description":"The access level for Accounts.","enum":["none","view","manage"]},"application_keys":{"type":"string","description":"The access level for Application Keys.","enum":["none","view","manage"]},"authentication":{"type":"string","description":"The access level for Authentication.","enum":["none","view","manage"]},"catalog_releases":{"type":"string","description":"The access level for Catalog Releases.","enum":["none","view","manage"]},"catalogs":{"type":"string","description":"The access level for Catalogs.","enum":["none","view","manage"]},"composer":{"type":"string","description":"The access level for Composer.","enum":["none","manage"]},"currencies":{"type":"string","description":"The access level for Currencies.","enum":["none","view","manage"]},"custom_apis":{"type":"string","description":"The access level for Custom APIs.","enum":["none","view","manage"]},"flows":{"type":"string","description":"The access level for Flows.","enum":["none","view","manage"]},"legacy_catalogs":{"type":"string","description":"The access level for Legacy Catalogs.","enum":["none","view","manage"]},"metrics":{"type":"string","description":"The access level for Metrics.","enum":["none","view"]},"orders":{"type":"string","description":"The access level for Orders.","enum":["none","view","manage"]},"payment_gateways":{"type":"string","description":"The access level for Payment Gateways.","enum":["none","view","manage"]},"personal_data":{"type":"string","description":"The access level for Personal Data.","enum":["none","view","manage"]},"price_books":{"type":"string","description":"The access level for Price Books.","enum":["none","view","manage"]},"products":{"type":"string","description":"The access level for Products.","enum":["none","view","manage"]},"promotions":{"type":"string","description":"The access level for Promotions.","enum":["none","view","manage"]},"settings":{"type":"string","description":"The access level for Settings.","enum":["none","view","manage"]},"subscription_billing":{"type":"string","description":"The access level for Subscription Billing.","enum":["none","view","manage"]},"subscription_jobs":{"type":"string","description":"The access level for Subscription Jobs.","enum":["none","view","manage"]},"subscription_offerings":{"type":"string","description":"The access level for Subscription Offerings.","enum":["none","view","manage"]},"subscription_subscribers":{"type":"string","description":"The access level for Subscription Subscribers.","enum":["none","view","manage"]},"team":{"type":"string","description":"The access level for Team.","enum":["none","view","manage"]},"webhooks":{"type":"string","description":"The access level for Webhooks.","enum":["none","view","manage"]}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Standard User Role.","example":"/v2/permissions/standard-user-roles/it-developer","type":["string","null"],"format":"uri","title":"LinkURI"}}}},"title":"StandardUserRole"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"not-found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## List Custom API Role Policies

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Custom API Role Policies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/permissions/custom-api-role-policies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of Custom API Role Policies

## Filtering
The following operators and attributes are available for [filtering](/guides/Getting-Started/filtering) Custom API Role Policies:

| Attribute        | Operators                     | Example                                                  |
|------------------|-------------------------------|----------------------------------------------------------|
| `id`             | `lt`,`le`,`eq`,`gt`,`ge`,`in` | `eq(id,3fa85f64-5717-4562-b3fc-2c963f66afa6)`            |
| `created_at`     | `lt`,`le`,`eq`,`gt`,`ge`      | `ge(created_at,2024-04-29T00:00:00.000Z)`                |
| `updated_at`     | `lt`,`le`,`eq`,`gt`,`ge`      | `le(updated_at,2024-04-29T00:00:00.000Z)`                |
| `custom_api_id`  | `eq`                          | `eq(custom_api_id,fded1d2a-8bb8-48b6-86a5-9eb05cc8626a)` |
| `role_id`        | `eq`                          | `eq(role_id,it-developer)`                               |

## Sorting
The following attributes are available for sorting. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with `-`, for example, `-updated_at`. The default sort order is `created_at` in descending order.
- `id`
- `created_at`
- `updated_at`

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0}},{"name":"filter","description":"Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.","in":"query","required":false,"schema":{"type":"string","format":"string"}},{"name":"sort","description":"Specifies the order in which Custom API Role Policies will be returned.","in":"query","required":false,"schema":{"type":"string","enum":["id","-id","created_at","-created_at","updated_at","-updated_at"],"example":"id","x-enumDescriptions":{"id":"Sort in increasing order of ID","-id":"Sort in decreasing order of ID","created_at":"Sort in increasing order of creation","-created_at":"Sort in decreasing order of creation","updated_at":"Sort in increasing order of last update","-updated_at":"Sort in decreasing order of last update"}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List of Custom API Role Policies","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Role Policy.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.","const":"custom_api_role_policy"},"create":{"type":"boolean","description":"Specifies if the Role can create a Custom API Entry."},"list":{"type":"boolean","description":"Specifies if the Role can retrieve a list of Custom API Entries."},"read":{"type":"boolean","description":"Specifies if the Role can get a Custom API Entry."},"update":{"type":"boolean","description":"Specifies if the Role can update a Custom API Entry."},"delete":{"type":"boolean","description":"Specifies if the Role can delete a Custom API Entry."},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Role Policy.","example":"/v2/permissions/custom-api-role-policies/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},"relationships":{"type":"object","properties":{"custom_api":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API.","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of the resource object.","const":"custom_api"}}}}},"role":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Role.","example":"it-developer"},"type":{"type":"string","description":"Specifies the type of the resource object.","enum":["standard_user_role","standard_shopper_role"]}}}}}},"title":"CustomAPIRolePolicyRelationships"}},"title":"CustomAPIRolePolicy"}},"meta":{"type":"object","properties":{"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results for the entire collection."}}},"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records for all pages.","example":100},"offset":{"type":"integer","description":"The current offset by number of pages.","example":0},"current":{"type":"integer","description":"The current number of pages.","example":1},"total":{"type":"integer","description":"The total number of pages.","example":1}}}},"title":"PaginationMeta"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"first":{"description":"Always the first page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"last":{"description":"Always `null` if there is only one page.","example":"/v2/settings/custom-apis?page[offset]=0&page[limit]=100","type":["string","null"],"format":"uri","title":"LinkURI"},"next":{"description":"Always `null` if there is only one page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"},"prev":{"description":"Always `null` if on the first page.","example":null,"type":["string","null"],"format":"uri","title":"LinkURI"}},"title":"PaginationLinks"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"Invalid filter: unknown field [version] specified in search filter, allowed fields are [api_type created_at description id name slug updated_at]\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## List Standard Shopper Roles

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Standard Shopper Roles"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/permissions/standard-shopper-roles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of Standard Shopper Roles

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List of Standard Shopper Roles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Standard Shopper Role."},"type":{"type":"string","description":"Specifies the type of the resource object, use `standard_shopper_role` for Standard Shopper Roles.","const":"standard_shopper_role"},"name":{"type":"string","description":"Specifies the name of the Standard Shopper Role."},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Standard Shopper Role.","example":"/v2/permissions/standard-shopper-roles/guest-shopper","type":["string","null"],"format":"uri","title":"LinkURI"}}}},"title":"StandardShopperRole"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## List Standard User Roles

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Standard User Roles"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/permissions/standard-user-roles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of Standard User Roles

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List of Standard User Roles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Standard User Role."},"type":{"type":"string","description":"Specifies the type of the resource object, use `standard_user_role` for Standard User Roles.","const":"standard_user_role"},"name":{"type":"string","description":"Specifies the name of the Standard User Role."},"access_levels":{"type":"object","description":"Specifies the access levels for each permission group.","properties":{"accounts":{"type":"string","description":"The access level for Accounts.","enum":["none","view","manage"]},"application_keys":{"type":"string","description":"The access level for Application Keys.","enum":["none","view","manage"]},"authentication":{"type":"string","description":"The access level for Authentication.","enum":["none","view","manage"]},"catalog_releases":{"type":"string","description":"The access level for Catalog Releases.","enum":["none","view","manage"]},"catalogs":{"type":"string","description":"The access level for Catalogs.","enum":["none","view","manage"]},"composer":{"type":"string","description":"The access level for Composer.","enum":["none","manage"]},"currencies":{"type":"string","description":"The access level for Currencies.","enum":["none","view","manage"]},"custom_apis":{"type":"string","description":"The access level for Custom APIs.","enum":["none","view","manage"]},"flows":{"type":"string","description":"The access level for Flows.","enum":["none","view","manage"]},"legacy_catalogs":{"type":"string","description":"The access level for Legacy Catalogs.","enum":["none","view","manage"]},"metrics":{"type":"string","description":"The access level for Metrics.","enum":["none","view"]},"orders":{"type":"string","description":"The access level for Orders.","enum":["none","view","manage"]},"payment_gateways":{"type":"string","description":"The access level for Payment Gateways.","enum":["none","view","manage"]},"personal_data":{"type":"string","description":"The access level for Personal Data.","enum":["none","view","manage"]},"price_books":{"type":"string","description":"The access level for Price Books.","enum":["none","view","manage"]},"products":{"type":"string","description":"The access level for Products.","enum":["none","view","manage"]},"promotions":{"type":"string","description":"The access level for Promotions.","enum":["none","view","manage"]},"settings":{"type":"string","description":"The access level for Settings.","enum":["none","view","manage"]},"subscription_billing":{"type":"string","description":"The access level for Subscription Billing.","enum":["none","view","manage"]},"subscription_jobs":{"type":"string","description":"The access level for Subscription Jobs.","enum":["none","view","manage"]},"subscription_offerings":{"type":"string","description":"The access level for Subscription Offerings.","enum":["none","view","manage"]},"subscription_subscribers":{"type":"string","description":"The access level for Subscription Subscribers.","enum":["none","view","manage"]},"team":{"type":"string","description":"The access level for Team.","enum":["none","view","manage"]},"webhooks":{"type":"string","description":"The access level for Webhooks.","enum":["none","view","manage"]}}},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Standard User Role.","example":"/v2/permissions/standard-user-roles/it-developer","type":["string","null"],"format":"uri","title":"LinkURI"}}}},"title":"StandardUserRole"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Permissions Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/permissions/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Permissions Introduction"}
>
</Heading>

A user's permissions are determined by their assigned role, which defines their level of access to APIs and Commerce Manager. These permissions ensure that users can only perform actions and access data relevant to their responsibilities.

With [Commerce Extensions](/docs/api/commerce-extensions/commerce-extensions-introduction), you can create Custom APIs to extend the functionality of Commerce. Using Custom API Role Policies, you can specify the permissions for each role, ensuring fine-grained control over who can interact with these Custom APIs.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Standard Shopper Roles

Standard Shopper Roles represent the roles of customers.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Standard User Roles

Standard User Roles represent the roles that can be assigned to users through Commerce Manager. These roles define the level of access a user has to Commerce Manager.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Update a Custom API Role Policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Custom API Role Policy"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/permissions/custom-api-role-policies/{custom-api-role-policy-id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update A Custom API Role Policy

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"custom-api-role-policy-id","description":"The ID of the Custom API Role Policy.","in":"path","required":true,"schema":{"type":"string"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.","const":"custom_api_role_policy"},"create":{"type":"boolean","description":"Specifies if the Role can create a Custom API Entry."},"list":{"type":"boolean","description":"Specifies if the Role can retrieve a list of Custom API Entries."},"read":{"type":"boolean","description":"Specifies if the Role can get a Custom API Entry."},"update":{"type":"boolean","description":"Specifies if the Role can update a Custom API Entry."},"delete":{"type":"boolean","description":"Specifies if the Role can delete a Custom API Entry."}}}}},"examples":{"Update Example":{"summary":"Update a Custom API Role Policy","value":{"data":{"type":"custom_api_role_policy","create":false,"list":false,"read":false,"update":false,"delete":false}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"A Custom API Role Policy","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the Custom API Role Policy.","format":"uuid"},"type":{"type":"string","description":"Specifies the type of the resource object, use `custom_api_role_policy` for Custom API Role Policies.","const":"custom_api_role_policy"},"create":{"type":"boolean","description":"Specifies if the Role can create a Custom API Entry."},"list":{"type":"boolean","description":"Specifies if the Role can retrieve a list of Custom API Entries."},"read":{"type":"boolean","description":"Specifies if the Role can get a Custom API Entry."},"update":{"type":"boolean","description":"Specifies if the Role can update a Custom API Entry."},"delete":{"type":"boolean","description":"Specifies if the Role can delete a Custom API Entry."},"links":{"type":"object","properties":{"self":{"description":"Specifies the URI of the Custom API Role Policy.","example":"/v2/permissions/custom-api-role-policies/3fa85f64-5717-4562-b3fc-2c963f66afa6","type":["string","null"],"format":"uri","title":"LinkURI"}}},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","description":"Specifies the date the entity is created.","example":"2017-01-10T11:41:19.244Z"},"updated_at":{"type":"string","description":"Specifies the date the entity is last updated.","example":"2017-01-10T11:41:19.244Z"}},"title":"Timestamps"}},"title":"Meta"},"relationships":{"type":"object","properties":{"custom_api":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Custom API.","example":"652e39d8-d613-493e-8c20-fef99ad6327a"},"type":{"type":"string","description":"Specifies the type of the resource object.","const":"custom_api"}}}}},"role":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the related Role.","example":"it-developer"},"type":{"type":"string","description":"Specifies the type of the resource object.","enum":["standard_user_role","standard_shopper_role"]}}}}}},"title":"CustomAPIRolePolicyRelationships"}},"title":"CustomAPIRolePolicy"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"missing-name":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"The field 'name' is required.\"\n    }\n  ]\n}\n"}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"not-found":{"summary":"Requested entity not found","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Not Found\",\n      \"status\": \"404\",\n      \"detail\": \"Not found\"\n    }\n  ]\n}\n"}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","format":"string","examples":["400"]},"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}}}}},"title":"Errors"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get Personal Data Erasure Request

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Personal Data Erasure Request"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/personal-data/erasure-requests/{erasure_request_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

This request serves to get an existing erasure request by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"erasure_request_id","in":"path","required":true,"description":"The id of the Personal-Data Erasure Request.","schema":{"type":"string"},"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the log entry."},"resource_type":{"type":"string","description":"The type of the data entry to be erased.","example":"account"},"resource_id":{"type":"string","format":"uuid","description":"The ID of the data entry to be erased (note that also all data entries in the personal data set will be erased).","example":"98140362-6caf-4829-b93d-953ac6adbe6e"},"type":{"type":"string","const":"erasure_request","description":"The type of the object. Always equal to `erasure_request`."},"initiator":{"type":"object","description":"Specifies who initiated the erasure request.","properties":{"access-token-email":{"type":"string","example":"accounts@elasticpath.com"},"access-token-id":{"type":"string","example":1222341536243516000},"access-token-name":{"type":"string","example":"elastic path test team"},"access-token-store-id":{"type":"string","format":"uuid","example":"15ea9633-278c-4807-80f7-2009fed63c7e"},"access-token-type":{"type":"string","example":"client-credentials-token"}}},"status":{"type":"string","description":"Specifies the status of the erasure request."},"status_description":{"type":"string","description":"Elaborates on the erasure request status."},"created_at":{"type":"string","description":"Specifies the status of the erasure request."},"updated_at":{"type":"string","description":"Elaborates on the erasure request status."},"links":{"type":"object","properties":{"self":{"type":"string","description":"The self link."}}}},"title":"ErasureRequestResponse","type":"object"}}},"examples":{"postErasureRequest":{"value":{"data":{"id":"fb25ecd9-c610-4659-97d6-0a7550ac0ddc","type":"erasure_request","resource_id":"98140362-6caf-4829-b93d-953ac6adbe6e","resource_type":"account","initiator":{"access-token-email":"accounts@molt.in","access-token-id":"1222341536243515939","access-token-name":"moltin test team","access-token-store-id":"15ea9633-278c-4807-80f7-2009fed63c7e","access-token-type":"client-credentials-token"},"status":"CREATED","status_description":"The erasure request successfully created","created_at":"2022-06-07T12:25:38.52Z","updated_at":"2022-06-07T12:25:38.69Z","links":{"self":"https://useast.api.elasticpath.com/v2/personal-data/erasure-requests/fb25ecd9-c610-4659-97d6-0a7550ac0ddc"}}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found-error":{"summary":"Not Found","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"not found\",\n      \"status\": \"404\",\n      \"title\": \"Not Found\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get all Personal Data Erasure Request

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Personal Data Erasure Request"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/personal-data/erasure-requests"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets a list of erasure requests for a specific resource id and resource type.

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

## Filtering

The following operator and attributes are **required** for [filtering](/guides/Getting-Started/filtering)
erasure requests.

| Operator | Description                                                                                          |
|:---------|:-----------------------------------------------------------------------------------------------------|
| `eq`     | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |

| Attribute       | Type | Operator | Example                                                 |
|:----------------| :--- | :--- |:--------------------------------------------------------|
| `resource_type` | `string` | `eq`  | `eq(resource_type,customer)`                            |
| `resource_id`   | `string` | `eq`  | `eq(resource_id,0f850c15-d643-480a-a2b4-9e3c26067178\)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":0}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"description":"Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.","schema":{"type":"string","format":"string","example":"eq(resource_id,0f850c15-d643-480a-a2b4-9e3c26067178)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the log entry."},"resource_type":{"type":"string","description":"The type of the data entry to be erased.","example":"account"},"resource_id":{"type":"string","format":"uuid","description":"The ID of the data entry to be erased (note that also all data entries in the personal data set will be erased).","example":"98140362-6caf-4829-b93d-953ac6adbe6e"},"type":{"type":"string","const":"erasure_request","description":"The type of the object. Always equal to `erasure_request`."},"initiator":{"type":"object","description":"Specifies who initiated the erasure request.","properties":{"access-token-email":{"type":"string","example":"accounts@elasticpath.com"},"access-token-id":{"type":"string","example":1222341536243516000},"access-token-name":{"type":"string","example":"elastic path test team"},"access-token-store-id":{"type":"string","format":"uuid","example":"15ea9633-278c-4807-80f7-2009fed63c7e"},"access-token-type":{"type":"string","example":"client-credentials-token"}}},"status":{"type":"string","description":"Specifies the status of the erasure request."},"status_description":{"type":"string","description":"Elaborates on the erasure request status."},"created_at":{"type":"string","description":"Specifies the status of the erasure request."},"updated_at":{"type":"string","description":"Elaborates on the erasure request status."},"links":{"type":"object","properties":{"self":{"type":"string","description":"The self link."}}}},"title":"ErasureRequestResponse"}},"meta":{"type":"object","required":["page","results"],"properties":{"results":{"type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":1}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","example":100},"offset":{"description":"The current offset by number of pages.","type":"integer","example":0},"current":{"description":"The current number of pages.","type":"integer","example":1},"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1}}}},"title":"PaginationMeta"},"links":{"required":["current","first","last","next","prev"],"type":"object","properties":{"current":{"description":"Always the current page.","type":["string","null"],"format":"uri"},"first":{"description":"Always the first page.","type":["string","null"],"format":"uri"},"last":{"description":"Always `null` if there is only one page.","type":["string","null"],"format":"uri"},"next":{"description":"Always `null` if there is only one page.","type":["string","null"]},"prev":{"description":"Always `null` if the user is on the first page.","type":["string","null"]}},"title":"PaginationLinks"}}},"examples":{"postErasureRequest":{"value":{"meta":{"page":{"limit":10,"offset":0,"current":1,"total":1},"results":{"total":1}},"data":[{"id":"43eb23ef-9a97-466f-9315-d0e0c9df25b5","type":"erasure_request","resource_id":"abe71c87-974d-4ced-9f83-6b8d5502b0e8","resource_type":"account","initiator":{"access-token-email":"accounts@molt.in","access-token-id":"1222341536243515939","access-token-name":"moltin test team","access-token-store-id":"15ea9633-278c-4807-80f7-2009fed63c7e","access-token-type":"client-credentials-token"},"status":"FAILURE","status_description":"There was an error processing your request, you can retry it or report it using the id","created_at":"2022-05-25T10:10:58.623Z","updated_at":"2022-05-25T10:10:58.676Z"},{"id":"eeb182ed-f929-4197-bb43-7104afa852f2","type":"erasure_request","resource_id":"74f98b7a-dbbf-49ed-b7a7-eaea766b8e38","resource_type":"address","initiator":{"access-token-email":"accounts@molt.in","access-token-id":"1222341536243515939","access-token-name":"moltin test team","access-token-store-id":"15ea9633-278c-4807-80f7-2009fed63c7e","access-token-type":"client-credentials-token"},"status":"SUCCESS","status_description":"The erasure request is successfully processed","created_at":"2022-05-26T08:25:37.618Z","updated_at":"2022-05-26T08:25:37.698Z"},{"id":"39787c4b-a338-4bd7-ace9-456d1ae8e90b","type":"erasure_request","resource_id":"3327fb93-b687-4c0c-a850-ee95e0303ef1","resource_type":"account","initiator":{"access-token-email":"accounts@molt.in","access-token-id":"1222341536243515939","access-token-name":"moltin test team","access-token-store-id":"15ea9633-278c-4807-80f7-2009fed63c7e","access-token-type":"client-credentials-token"},"status":"FAILURE","status_description":"There was an error processing your request, you can retry it or report it using the id","created_at":"2022-05-26T08:48:56.183Z","updated_at":"2022-05-26T08:48:56.365Z"}],"links":{"current":"https://useast.api.elasticpath.com/v2/personal-data/erasure-requests?filter=eq(resource_type,account_member):eq(resource_id,00000000-0000-1000-8000-000f00000300)&page[offset]=0&page[limit]=10","first":"https://useast.api.elasticpath.com/v2/personal-data/erasure-requests?filter=eq(resource_type,account_member):eq(resource_id,00000000-0000-1000-8000-000f00000300)&page[offset]=0&page[limit]=10","last":"https://useast.api.elasticpath.com/v2/personal-data/erasure-requests?filter=eq(resource_type,account_member):eq(resource_id,00000000-0000-1000-8000-000f00000300)&page[offset]=0&page[limit]=10","next":"null","prev":"null"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"summary":"Unauthorized","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Unauthorized\",\n      \"status\": \"401\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get Logs Time-to-Live (TTL) Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Logs Time-to-Live (TTL) Settings"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings/logs-ttl"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get Logs Time-to-Live (TTL) Settings

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"days":{"type":"integer","description":"The number of days to retain the logs. Allowed values are between 1 and 365.","minimum":1,"maximum":365,"example":10},"type":{"type":"string","const":"time_to_live","description":"The type of the object. Always equal to `time_to_live`."}},"title":"LogsTtl"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"summary":"Unauthorized","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Unauthorized\",\n      \"status\": \"401\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get Personal Data Logs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Personal Data Logs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/personal-data/logs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets a list of logs for a specific resource id and resource type.

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

:::note
* This request is only accessible to `client_credentials` token users with `Seller Admin`, `Support` and `IT` roles.
* Non `client_credentials` token users cannot access this endpoint. See [Permissions](/docs/authentication/tokens/permissions).
* This request requires a filter for `resource_type` and `resource_id`.
  :::

## Filtering

The following operator and attributes are **required** for [filtering](/guides/Getting-Started/filtering) erasure requests.

| Operator | Description                                                                                          |
|:---------|:-----------------------------------------------------------------------------------------------------|
| `eq`     | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |

| Attribute         | Type     | Operator | Example                                                   |
| :---------------- | :---     | :---     | :-------------------------------------------------------- |
| `resource_type`   | `string` | `eq`     | `eq(resource_type,customer)`                              |
| `resource_id`     | `string` | `eq`     | `eq(resource_id,0f850c15-d643-480a-a2b4-9e3c26067178)`    |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":0}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"description":"Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.","schema":{"type":"string","format":"string","example":"eq(resource_id,0f850c15-d643-480a-a2b4-9e3c26067178)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the log entry.","example":"faf8c40f-a680-40ae-b7bc-78533bbdd8c3"},"store_id":{"type":"string","format":"uuid","description":"The unique identifier for the store id.","example":"00000000-0000-1000-8000-000000000000"},"type":{"type":"string","const":"personal_data_log_entry","description":"The type of the object. Always equal to `personal_data_log_entry`."},"initiator":{"type":"object","description":"Specifies who initiated the personal data change.","properties":{"access-token-email":{"type":"string","example":"accounts@elasticpath.com"},"access-token-id":{"type":"string","example":1222341536243516000},"access-token-name":{"type":"string","example":"elastic path test team"},"access-token-store-id":{"type":"string","format":"uuid","example":"15ea9633-278c-4807-80f7-2009fed63c7e"},"access-token-type":{"type":"string","example":"client-credentials-token"}}},"time":{"type":"string","description":"Specifies the time when the change happened.","example":"2022-04-29T10:51:14.374Z"},"event_type":{"type":"string","description":"Specifies the type of the event.","example":"user-authentication-info.event.created"},"delta":{"type":"object","description":"Includes fields that were changed as a result of the event.","properties":{"email":{"type":"string","example":"some@eamil.com"},"id":{"type":"string","format":"uuid","example":"00000000-0000-1000-8000-111111111112"},"name":{"type":"string","example":"some_name"},"realm_id":{"type":"string","example":"00000000-0000-1000-8000-111111111111"},"store_id":{"type":"string","format":"uuid","example":"00000000-0000-1000-8000-000000000000"},"type":{"type":"string","example":"user-authentication-info"}}},"resource_id":{"type":"string","description":"The ID of the data entry that was changed.","example":"00000000-0000-1000-8000-111111111112"},"resource_type":{"type":"string","description":"The type of the data entry that was changed.","example":"user-authentication-info"},"relationships":{"type":"object","properties":{"resource_path":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"http://www.elaticpath.com"}}}}}},"title":"PersonalDataLog"}},"meta":{"type":"object","required":["page","results"],"properties":{"results":{"type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":1}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","example":100},"offset":{"description":"The current offset by number of pages.","type":"integer","example":0},"current":{"description":"The current number of pages.","type":"integer","example":1},"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1}}}},"title":"PaginationMeta"},"links":{"required":["current","first","last","next","prev"],"type":"object","properties":{"current":{"description":"Always the current page.","type":["string","null"],"format":"uri"},"first":{"description":"Always the first page.","type":["string","null"],"format":"uri"},"last":{"description":"Always `null` if there is only one page.","type":["string","null"],"format":"uri"},"next":{"description":"Always `null` if there is only one page.","type":["string","null"]},"prev":{"description":"Always `null` if the user is on the first page.","type":["string","null"]}},"title":"PaginationLinks"}}},"examples":{"getLogs":{"value":{"data":[{"id":"faf8c40f-a680-40ae-b7bc-78533bbdd8c3","store_id":"00000000-0000-1000-8000-000000000000","type":"personal_data_log_entry","initiator":{"access-token-email":"accounts@molt.in","access-token-id":"1222341536243515939","access-token-name":"moltin test team","access-token-store-id":"15ea9633-278c-4807-80f7-2009fed63c7e","access-token-type":"client-credentials-token"},"time":"2022-04-29T10:51:14.374Z","event_type":"user-authentication-info.event.created","delta":{"email":"some@email.com","id":"00000000-0000-1000-8000-111111111112","name":"some_name","realm_id":"00000000-0000-1000-8000-111111111111","store_id":"00000000-0000-1000-8000-000000000000","type":"user-authentication-info"},"resource_id":"00000000-0000-1000-8000-111111111112","resource_type":"user-authentication-info","relationships":{"resource_path":{"url":"http://www.elaticpath.com"}}}],"meta":{"page":{"limit":100,"offset":0,"current":1,"total":1},"results":{"total":1}},"links":{"current":"https://useast.api.elasticpath.com/v2/personal-data/logs?page[offset]=0&page[limit]=20","first":"https://useast.api.elasticpath.com/v2/personal-data/logs?page[offset]=0&page[limit]=20","last":"https://useast.api.elasticpath.com/v2/personal-data/logs?page[offset]=0&page[limit]=20","next":"null","prev":"null"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-filter":{"summary":"Required filter missing","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"bad filter: resource_id and resource_type are the filter fields that are both mandatory and only they are allowed\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get Personal Data Related Data Entries

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Personal Data Related Data Entries"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/personal-data/related-data-entries"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets a list of related data entries filtered by specific resource id and resource type.

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

:::note

* This request is only accessible to `client_credentials` token users with `Seller Admin`, `Support` and `IT` roles.
* Non `client_credentials` token users cannot access this endpoint. See [Permissions](/docs/authentication/tokens/permissions).
* This request requires a filter for `resource_type` and `resource_id`.

:::

## Filtering

The following operator and attributes are **required** for [filtering](/guides/Getting-Started/filtering) erasure requests.

| Operator | Description                                                                                          |
|:---------|:-----------------------------------------------------------------------------------------------------|
| `eq`     | Checks whether the values of two operands are equal. If the values are equal, the condition is true. |

| Attribute         | Type     | Operator | Example                                                   |
| :---------------- | :---     | :---     | :-------------------------------------------------------- |
| `resource_type`   | `string` | `eq`     | `eq(resource_type,customer)`                              |
| `resource_id`     | `string` | `eq`     | `eq(resource_id,0f850c15-d643-480a-a2b4-9e3c26067178)`    |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":0}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"description":"Filter attributes. For more information, see the [Filtering](/guides/Getting-Started/filtering) section.","schema":{"type":"string","format":"string","example":"eq(resource_id,0f850c15-d643-480a-a2b4-9e3c26067178)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"resource_type":{"type":"string","description":"The type of a related data entry.","example":"user-authentication-info"},"resource_id":{"type":"string","format":"uuid","description":"The ID of a related data entry.","example":"00000000-0000-1000-8000-111111111112"},"type":{"type":"string","const":"related_data_entry","description":"The type of the object. Always equal to `related_data_entry`."}},"title":"RelatedDataEntry"}},"meta":{"type":"object","required":["page","results"],"properties":{"results":{"type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":1}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","example":100},"offset":{"description":"The current offset by number of pages.","type":"integer","example":0},"current":{"description":"The current number of pages.","type":"integer","example":1},"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1}}}},"title":"PaginationMeta"},"links":{"required":["current","first","last","next","prev"],"type":"object","properties":{"current":{"description":"Always the current page.","type":["string","null"],"format":"uri"},"first":{"description":"Always the first page.","type":["string","null"],"format":"uri"},"last":{"description":"Always `null` if there is only one page.","type":["string","null"],"format":"uri"},"next":{"description":"Always `null` if there is only one page.","type":["string","null"]},"prev":{"description":"Always `null` if the user is on the first page.","type":["string","null"]}},"title":"PaginationLinks"}}},"examples":{"getLogs":{"value":{"data":[{"resource_id":"00000000-0000-1000-8000-111111111112","type":"related_data_entry","resource_type":"user-authentication-info"}],"meta":{"page":{"limit":20,"offset":0,"current":1,"total":1},"results":{"total":1}},"links":{"current":"https://useast.api.elasticpath.com/v2/personal-data/related-data-entries?page[offset]=0&page[limit]=20","first":"https://useast.api.elasticpath.com/v2/personal-data/related-data-entries?page[limit]=20&page[offset]=0","last":"https://useast.api.elasticpath.com/v2/personal-data/related-data-entries?page[offset]=0&page[limit]=20","next":"null","prev":"null"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-filter":{"summary":"Required filter missing","value":"{\n  \"errors\": [\n    {\n      \"detail\": \"bad filter: resource_id and resource_type are the filter fields that are both mandatory and only they are allowed\",\n      \"status\": \"400\",\n      \"title\": \"Bad Request\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Logs Time to Live Settings

You can use the Logs TTL Settings endpoint to retrieve and update settings controlling logs time-to-live (TTL).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Personal Data Erasure Requests

Erasure requests enable you to exercise the right, referred to in regulations such as GDPR, as the right to be
forgotten or right to erase.
Erasure requests allow you to wipe out personal data from Commerce in an automated way, including:

* All related resources (for example, addresses, customers, and so on.)
* Personal Data Logs

Erasure requests can be created for any data entry in the personal data set (see [Personal Data Concept](/docs/api/personal-data/personal-data-introduction) for details), and the result is the same.

:::note
Currently, it does not include flows or data external to Commerce.
:::

Erasure requests are processed asynchronously. The POST requests return immediately, and processing continues in
the background. You can use the GET endpoint to poll for results until you see `{..."status":"SUCCESS"...}` in the
response body.

In the unlikely event an erasure request fails (if the status is not equal to `SUCCESS`), you are advised to retry
by creating another erasure request. If the problem persists, contact Support.

:::note
Currently, personal data management is only enabled for a limited set of endpoints. See
the [personal data concepts page](/docs/api/personal-data/personal-data-introduction) for the list of endpoints that support personal data
management.
:::

Seller Admin & IT users have full access to Erasure Requests, and Support users have read access.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Personal Data Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/personal-data/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Personal Data Introduction"}
>
</Heading>

In Commerce, every change to a user’s personal data is logged.

Personal data sets are groups of data items that are related to each other. For example, customer, addresses, and authentication information. The contents of a personal data set is dynamic. Data items are attached to each other automatically as they are created or updated.

The API allows you to fetch these logs, including the list of related data items. In other words, the data items that belong to the same personal data set.

Log entries are kept in the system for a limited time. You can configure the retention period using the Logs Time-to-live (TTL) settings API. The default retention period is 365 days for production store types and 7 days for other store types.

## Personal Data Resource Types

| Entity type                               | Endpoint                                                                                                                                              | Documentation                                                                                                    |
|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| customer                                  | `v2/customers/{id}`                                                                                                                                   | [Customers](/docs/customer-management/customer-management-api/customer-management-api-overview)                  |
| account                                   | `v2/accounts/{id}`                                                                                                                                    | [Accounts](/docs/api/accounts/post-v-2-accounts)                                                                 |
| account-member                            | `v2/account-members/{id}`                                                                                                                             | [Account Members](/docs/api/accounts/account-members)                                                            |
| account-membership                        | `v2/accounts/{accountId}/account-memberships/{id}`                                                                                                    | [Account Memberships](/docs/api/accounts/account-membership)                                                     |
| address                                   | `v2/customers/{customerId}/addresses/{id}`; `v2/accounts/{accountId}/addresses/{id}`                                                                  | [Addresses](/docs/api/addresses/addresses-introduction)                                                          |
| user-authentication-info                  | `v2/authentication-realms/{realmId}/user-authentication-info/{id}`                                                                                    | [User Authentication Info](/docs/api/single-sign-on/user-authentication-infos)                                   |
| user-authentication-oidc-profile-info     | `v2/authentication-realms/{authenticationRealmId}/user-authentication-info/{userAuthenticationInfoId}/user-authentication-oidc-profile-info/{id}`     | [User Authentication OIDC Profile Info](/docs/api/single-sign-on/user-authentication-oidc-profile-infos)         |
| user-authentication-password-profile-info | `v2/authentication-realms/{authenticationRealmId}/user-authentication-info/{userAuthenticationInfoId}/user-authentication-password-profile-info/{id}` | [User Authentication Password Profile Info](/docs/api/single-sign-on/user-authentication-password-profile-infos) |
| order                                     | `v2/orders/{id}`                                                                                                                                      | [Orders](/docs/api/carts/orders)                                                                                 |

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Personal Data Logs

When a user’s personal data is changed, an event is logged by Commerce. You can use the Personal Data Logs endpoint to access these logs.

This API is read only, and you cannot add, update, or delete logs using this API.

The API only allows you to read all logs for a particular data entry (specified in the filter GET parameter).

:::note
Currently, personal data management is only enabled for a limited set of endpoints. See the [personal data concepts page](/docs/api/personal-data/personal-data-introduction) for the list of endpoints that support personal data management.
:::

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Personal Data Related Data Entries

This is a supplementary endpoint for the [logs](/docs/api/personal-data/logs-time-to-live-settings) endpoint. It allows you to view all data entries that are related to the
resource specified in the filter. For example, a user can get all data items that relate to a customer, such as addresses or user authentication info.

This API is read only, and you cannot add, update, or delete anything using this API.

The API only allows you to list related data items for a particular data entry (specified in the filter GET parameter).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Create Personal Data Erasure Request

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Personal Data Erasure Request"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/personal-data/erasure-requests"}
  context={"endpoint"}
>
  
</MethodEndpoint>

This request serves to create a new erasure request for a given resource ID and Type. All resources that belong to the same personal data set will be erased.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type"],"properties":{"resource_type":{"type":"string","description":"The type of the data entry to be erased.","example":"account"},"resource_id":{"type":"string","format":"uuid","description":"The ID of the data entry to be erased (note that also all data entries in the personal data set will be erased).","example":"98140362-6caf-4829-b93d-953ac6adbe6e"},"type":{"type":"string","const":"erasure_request","description":"The type of the object. Always equal to `erasure_request`."}},"title":"ErasureRequest"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the log entry."},"resource_type":{"type":"string","description":"The type of the data entry to be erased.","example":"account"},"resource_id":{"type":"string","format":"uuid","description":"The ID of the data entry to be erased (note that also all data entries in the personal data set will be erased).","example":"98140362-6caf-4829-b93d-953ac6adbe6e"},"type":{"type":"string","const":"erasure_request","description":"The type of the object. Always equal to `erasure_request`."},"initiator":{"type":"object","description":"Specifies who initiated the erasure request.","properties":{"access-token-email":{"type":"string","example":"accounts@elasticpath.com"},"access-token-id":{"type":"string","example":1222341536243516000},"access-token-name":{"type":"string","example":"elastic path test team"},"access-token-store-id":{"type":"string","format":"uuid","example":"15ea9633-278c-4807-80f7-2009fed63c7e"},"access-token-type":{"type":"string","example":"client-credentials-token"}}},"status":{"type":"string","description":"Specifies the status of the erasure request."},"status_description":{"type":"string","description":"Elaborates on the erasure request status."},"created_at":{"type":"string","description":"Specifies the status of the erasure request."},"updated_at":{"type":"string","description":"Elaborates on the erasure request status."},"links":{"type":"object","properties":{"self":{"type":"string","description":"The self link."}}}},"title":"ErasureRequestResponse"}}},"examples":{"postErasureRequest":{"value":{"data":{"id":"fb25ecd9-c610-4659-97d6-0a7550ac0ddc","type":"erasure_request","resource_id":"98140362-6caf-4829-b93d-953ac6adbe6e","resource_type":"account","initiator":{"access-token-email":"accounts@molt.in","access-token-id":"1222341536243515939","access-token-name":"moltin test team","access-token-store-id":"15ea9633-278c-4807-80f7-2009fed63c7e","access-token-type":"client-credentials-token"},"status":"CREATED","status_description":"The erasure request successfully created","created_at":"2022-06-07T12:25:38.52Z","updated_at":"2022-06-07T12:25:38.69Z","links":{"self":"https://useast.api.elasticpath.com/v2/personal-data/erasure-requests/fb25ecd9-c610-4659-97d6-0a7550ac0ddc"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"Validation failed: field 'Type' on the 'ttl-type' tag.\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Update Logs Time-to-Live (TTL) Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Logs Time-to-Live (TTL) Settings"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings/logs-ttl"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update Logs Time-to-Live (TTL) Settings

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type"],"properties":{"days":{"type":"integer","description":"The number of days to retain the logs. Allowed values are between 1 and 365.","minimum":1,"maximum":365,"example":10},"type":{"type":"string","const":"time_to_live","description":"The type of the object. Always equal to `time_to_live`."}},"title":"LogsTtl"}}},"examples":{"update-logs-ttl":{"summary":"Update Logs TTL","value":{"data":{"days":10,"type":"time_to_live"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"days":{"type":"integer","description":"The number of days to retain the logs. Allowed values are between 1 and 365.","minimum":1,"maximum":365,"example":10},"type":{"type":"string","const":"time_to_live","description":"The type of the object. Always equal to `time_to_live`."}},"title":"LogsTtl"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"summary":"Required field missing","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Bad Request\",\n      \"status\": \"400\",\n      \"detail\": \"Validation failed: field 'Type' on the 'ttl-type' tag.\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Cancel a Job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cancel a Job"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/promotions/{promotionID}/jobs/{jobID}/cancel"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Cancels an asynchronous job whose status is pending or processing.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of a promotion."},{"name":"jobID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of a job to be canceled."},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Job canceled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a job is created."},"type":{"description":"Always `promotion_job`.","type":"string","example":"promotion_job"},"promotion_id":{"description":"A unique ID of a promotion.","type":"string"},"job_type":{"description":"The type of job you want to run. For example, `code_generate` to generate codes or `code_export` to export codes.","type":"string"},"name":{"description":"The name of the job. The maximum length allowed is 50 characters.","type":"string"},"parameters":{"type":"object"},"status":{"description":"The status of the job. See [Overview](/docs/api/promotions/promotion-jobs).","type":"string"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The creation date of the job.","type":"string","format":"date-time"},"updated_at":{"description":"The last updated date of the job.","type":"string","format":"date-time"}}}}}},"title":"PromotionJob"}}}}}}}}
>
  
</StatusCodes>

---

## Create a Promotion Job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Promotion Job"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/promotions/{promotionID}/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to create an asynchronous job to generate codes and export promotion codes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of a promotion."},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"description":"Must be set to `promotion_job`.","type":"string","example":"promotion_job"},"job_type":{"description":"Specifies the type of task you want to run. For example, `code_generate` to generate codes or `code_export` to export codes.","type":"string","enum":["code_generate","code_export"]},"name":{"type":"string","description":"Represents the name of the job. The maximum allowed length is 50.","maxLength":50},"parameters":{"type":"object","properties":{"number_of_codes":{"type":"integer","description":"Specifies the number of codes to be generated. It cannot be greater than the maximum number of codes per promotion, which defaults at 1000.","maximum":1000},"max_uses_per_code":{"type":"integer","description":"Specifies the maximum number of usages of a code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times."},"consume_unit":{"type":"string","description":"Specifies whether the usage limitation is at the item-level or cart-level.","enum":["per_item","per_cart"]},"code_prefix":{"type":"string","description":"Indicates the prefix to include with the promotion code. For example, when the generated value is *aa2b-3c4d* and the prefix value is set as *summer*, the promotion code becomes *summer-aa2b-3c4d*."},"code_length":{"type":"integer","description":"Specifies the code length, which ranges from 8 to 16 characters. The default code length is eight characters, and a dash is added after every four characters in the code. For example, *aa2b-3c4d*."}}}}},"examples":{"generate-promotion-codes":{"summary":"Generate Promotion Codes Job","value":{"type":"promotion_job","job_type":"code_generate","name":"Summer Sale Job","parameters":{"number_of_codes":1,"max_uses_per_code":1,"consume_unit":"per_cart","code_prefix":"Summer-","code_length":10}}},"export-promotion-codes":{"summary":"Export Promotion Codes Job","value":{"type":"promotion_job","job_type":"code_export","name":"Export Codes Job"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Promotion job created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a job is created."},"type":{"description":"Always `promotion_job`.","type":"string","example":"promotion_job"},"promotion_id":{"description":"A unique ID of a promotion.","type":"string"},"job_type":{"description":"The type of job you want to run. For example, `code_generate` to generate codes or `code_export` to export codes.","type":"string"},"name":{"description":"The name of the job. The maximum length allowed is 50 characters.","type":"string"},"parameters":{"type":"object"},"status":{"description":"The status of the job. See [Overview](/docs/api/promotions/promotion-jobs).","type":"string"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The creation date of the job.","type":"string","format":"date-time"},"updated_at":{"description":"The last updated date of the job.","type":"string","format":"date-time"}}}}}},"title":"PromotionJob"}}}}}}}}
>
  
</StatusCodes>

---

## Create a Promotion

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Promotion"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/promotions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can use this endpoint to create the following types of promotion:
 - Cart Fixed Discount Promotion
 - Cart Percent Discount Promotion
 - X for Y Discount Promotion
 - X for Amount Discount Promotion
 - Fixed Bundle Discount Promotion
 - Item Fixed Discount Promotion
 - Item Percent Discount Promotion
 - Free Gift Promotion

### The `schema` object

Promotions are defined by schemas that are used internally to verify promotions and calculate discounts. You must define a schema when you create the promotion. For more information, see the schema.exclude criteria and the targeting fields criteria.

#### The `schema.exclude` criteria

When creating a promotion, you can specify when it **should not** be applied. The promotion will not be applied on any cart (or cart item, depending on the promotion type) that fulfills at least one of the `schema.exclude` criteria. The following criteria can be set to exclude items from a promotion:

- `schema.exclude.targets`
- `schema.exclude.nodes`
- `schema.exclude.attributes`
- `schema.exclude.conditions`

For example, if you want to create a promotion with value as *SKU1* in `schema.exclude.targets` and and color *yellow* and size *small* in `schema.exclude.attributes`, then any products with *SKU1* or the color *yellow* or the size *small* will be excluded from the promotion.

To exclude products from a promotion based on multiple conditions at the same time, use `schema.exclude.conditions`. For example, use `schema.exclude.conditions` to exclude items that are both *yellow* in color and *small* in size.

#### The targeting fields criteria

When creating a promotion, you can also specify when it **should** be applied. To define the targeted products, use the following fields:

  - `schema.target_catalogs`
  - `schema.targets`
  - `schema.target_nodes`
  - `schema.target_attributes`
  - `schema.target_conditions`

The cart item's catalog is verified if you define the `schema.target_catalogs` field. If the item is in any of the targeted catalogs specified in `schema.target_catalogs`, the promotion will be applied. If the item is not in any of the catalogs, the promotion will not be applied.

Then, the cart item is verified to see if it fulfills at least one criteria of any of the four other targeting fields. In other words, the `schema` targeting fields such as `schema.targets`, `schema.target_nodes`, `schema.target_attributes` and `schema.target_conditions` create *OR* targeting conditions.

For example, if you create a promotion with values as *SKU1* in `schema.targets` and color *yellow* and size *small* in `schema.target_attributes`, then it will be applied to any products with *SKU1* or the color *yellow* or the size *small*.

To create a promotion that targets products based on multiple conditions at the same time, use `schema.target_conditions`. For example, use it to target items that are both *yellow* in color and *small* in size.

:::note

For Cart Fixed Discount Promotion and Cart Percent Discount Promotion, the cart item's catalog is verified if you define the `schema.target_catalogs` field. If the item is in any of the targeted catalogs specified in `schema.target_catalogs`, the promotion will be applied. If the item is not in any of the catalogs, the promotion will not be applied.

:::

:::caution

- Line-item discounts are only supported by the line calculation method. For more information about this method, see the Calculation Method section.
- Hierarchy-based promotions are not supported for fixed bundle discount promotion and free gift promotion. To promote a bundle, create the bundle in Product Experience Manager, and then create a promotion for that bundle. For more information, see Bundles in Product Experience Manager.
- For Free Gift Promotion, we recommend using `auto_add_free_gift` feature with `automatic` setting enabled. When `automatic` is set to `true`, it indicates that promotions are added automatically, and discounts are applied accordingly. If you enable the `auto_add_free_gift`, but do not enable the `automatic` setting, gift items will be added without discounts. In this case, shoppers need to apply coupon codes twice, first to add the gift item and then to apply the discount.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"required":["data"],"properties":{"data":{"type":"object","oneOf":[{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}],"discriminator":{"propertyName":"promotion_type","mapping":{"fixed_discount":{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"percent_discount":{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_fixed_discount":{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_percent_discount":{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},"x_for_y":{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},"x_for_amount":{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},"bundle_fixed_discount":{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},"bundle_gift":{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}}},"required":["promotion_type"],"properties":{"promotion_type":{"type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]}},"title":"Data.PromotionObject"}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"description":"Specifies the type of the resource. The type of resource for promotions is, `promotion_codes`.","type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","oneOf":[{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}],"discriminator":{"propertyName":"promotion_type","mapping":{"fixed_discount":{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"percent_discount":{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_fixed_discount":{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_percent_discount":{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},"x_for_y":{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},"x_for_amount":{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},"bundle_fixed_discount":{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},"bundle_gift":{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}}},"required":["promotion_type"],"properties":{"promotion_type":{"type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]}},"title":"Data.PromotionObject"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}}}}
>
  
</StatusCodes>

---

## Create Promotion Codes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Promotion Codes"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/promotions/{promotionID}/codes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to create promotion codes for a specific promotion.

:::note

When a promotion expires, the promotion codes attached to the promotion automatically become invalid. However, when you re-enable the expired promotion, the promotion codes attached to the promotion are deleted.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","description":"The unique identifier of the promotion.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Data.PromotionsCodesRequest","type":"object","properties":{"codes":{"type":"array","items":{"title":"Data.CodeRequest","type":"object","properties":{"code":{"description":"Specifies the string to use as a code for the promotion.","type":"string","examples":["ZXY_CBA"]},"consume_unit":{"description":"Specifies whether the code is applied to a line item or cart. The options are `per_item` or `per_cart`. The default setting is per_cart, which is applied at cart level. The `per_item` setting specifies how many times a buyer can use a promotion code on promotion items in a cart. For example, in a store that offers 50% off on SKU1, but limits the maximum usage of the promotion code to two, buyer can apply the promotion to SKU1 up to 2 times if cart has two quantities of SKU1. The third SKU1 is sold for regular price. The code usage is applied at checkout. You must set the automatic setting to `false` and create a code for this promotion to work.","type":"string","examples":["per_item"]},"user":{"description":"Specifies the users who can use the code. You can use the customer object ID or an array of customer object IDs. For more information, see the [Create a customer](/docs/customer-management/customer-management-api/create-a-customer) section. Additionally, you could pass any identifying string to the promotions service that identifies a user.","type":"string","examples":["{customerID}"]},"uses":{"description":"Specifies the maximum number of times the code can be used. If no value is set, the shopper can use the code any number of times.","type":"number","examples":[10]}}},"description":""},"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion_codes`.","type":"string","examples":["promotion_codes"]}}}]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"description":"Specifies the type of the resource. The type of resource for promotions is, `promotion_codes`.","type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","oneOf":[{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}],"discriminator":{"propertyName":"promotion_type","mapping":{"fixed_discount":{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"percent_discount":{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_fixed_discount":{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_percent_discount":{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},"x_for_y":{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},"x_for_amount":{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},"bundle_fixed_discount":{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},"bundle_gift":{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}}},"required":["promotion_type"],"properties":{"promotion_type":{"type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]}},"title":"Data.PromotionObject"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}}}}
>
  
</StatusCodes>

---

## Delete a Promotion Code

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Promotion Code"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/promotions/{promotionID}/codes/{code}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to delete a single promotion code.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","description":"Specifies the unique identifier of the promotion associated with the codes.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"code","in":"path","description":"Specifies the code that you want to delete.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"detail":"promotion not found","status":404,"title":"Not Found"}]}]}}}}}
>
  
</StatusCodes>

---

## Delete a Promotion

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Promotion"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/promotions/{promotionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to delete a specific promotion.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","description":"The ID of the promotion that you want to delete.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}}}}
>
  
</StatusCodes>

---

## Delete Multiple Promotion Codes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Multiple Promotion Codes"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/promotions/{promotionID}/codes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to delete multiple promotion codes within a specific promotion.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","description":"The ID of the promotion associated with the codes.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"detail":"promotion not found","status":404,"title":"Not Found"}]}]}}}}}
>
  
</StatusCodes>

---

## Get a Promotion History

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Promotion History"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/promotions/{promotionID}/history"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to retrieve a promotion history.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","description":"The ID of the promotion.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"description":"Specifies the type of the resource. The type of resource for promotions is, `promotion_codes`.","type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"array","items":{"type":"object","oneOf":[{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}],"discriminator":{"propertyName":"promotion_type","mapping":{"fixed_discount":{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"percent_discount":{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_fixed_discount":{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_percent_discount":{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},"x_for_y":{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},"x_for_amount":{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},"bundle_fixed_discount":{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},"bundle_gift":{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}}},"required":["promotion_type"],"properties":{"promotion_type":{"type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]}},"title":"Data.PromotionObject"}},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string"},"first":{"description":"Always the first page.","type":"string"},"last":{"description":"If there is only one page, it returns `null`.","type":"string"},"next":{"description":"If there is only one page, it returns `null`.","type":"string"},"prev":{"description":"If the user is on the first page, it returns `null`.","type":"string"}},"title":"Response.PageLinks"},"meta":{"title":"Response.Meta.Promotions","type":"object","properties":{"page":{"type":"object","properties":{"current":{"description":"The current page.","type":"integer"},"limit":{"description":"The maximum number of records per page for this response. You can set this value up to 100.","type":"integer"},"offset":{"description":"The current offset by number of records, not pages. Offset is zero-based.","type":"integer"},"total":{"description":"The total page count.","type":"integer"}},"title":"Response.PaginationPage"},"results":{"type":"object","properties":{"total":{"description":"The total number of results.","type":"integer"}},"title":"Response.PaginationResults"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}}}}
>
  
</StatusCodes>

---

## Get a Promotion

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Promotion"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/promotions/{promotionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a promotion.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","description":"The ID of the promotion.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"description":"Specifies the type of the resource. The type of resource for promotions is, `promotion_codes`.","type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","oneOf":[{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}],"discriminator":{"propertyName":"promotion_type","mapping":{"fixed_discount":{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"percent_discount":{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_fixed_discount":{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_percent_discount":{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},"x_for_y":{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},"x_for_amount":{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},"bundle_fixed_discount":{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},"bundle_gift":{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}}},"required":["promotion_type"],"properties":{"promotion_type":{"type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]}},"title":"Data.PromotionObject"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}}}}
>
  
</StatusCodes>

---

## Get all Promotions

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Promotions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/promotions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all promotions.

:::note

You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).

:::

### Filtering

The following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](https://elasticpath.dev/guides/Getting-Started/filtering#supported-characters).

Use `code` filter to search codes within promotions.

| Attribute | Type | Operator     | Example                            |
|:-----|:---------|:---------|:----------------------------------------|
| `code` |  `string`   | `eq` | `eq(code,some_code)`          | 

For filtering advanced promotion usages, pass the `EP-Public-Search-Type=cm_search` header. Advanced search filtering is only applicable when the promotion code is consumed and the promotion is not deleted.

| Attribute | Type | Operator     | Example                            |
|:-----|:---------|:---------|:----------------------------------------|
| `promo_id`                    | `string`        |  `eq`	                  | `eq(promo_id, 69c63c9d-8ccf-44b1-8e98-1e7feebfb581)` |
| `promo_name`                  |`string`	      | `eq`, `like`	              | `eq(promo_name,cart percent discount)` |
| `promo_type`                  | `string`	      | `eq`	                  | `eq(promo_type,fixed_discount)` |
| `promo_status`                | `string`	      | `eq`	                  | `eq(promo_status,Running)` |
| `promo_checkouts`            | `string`	      | `eq`,`gt`, `ge`, `lt`, `le`	      | `eq(promo_checkouts,2)` |
| `promo_skus_prod_ids`         |	`string`	  | `eq`, `like`	              | `eq(promo_skus_prod_ids, sku1)` |
| `promo_start_date`            |	`string`	| `eq`, `gt`, `gr`, `lt`, `le`      | `eq(promo_start_date,2023-01-01)` |
| `promo_end_date`              |	`string`  | `eq`, `gt`, `gr`, `lt`, `le`	  | `eq(promo_end_date,2050-06-15)` |
| `code_id`	                  | `string`  | `eq`                  | `eq(promo_id,2ea0cd1d-43a9-441b-b03f-3cab84aaee0c):eq(code_id,14b55e6c-3f80-436e-a90a-4de5f0e36240)`  |
| `code_code`                   |  `string` | `eq`, `like`                | 	`eq(code_code,cart_fixed_10)` |
| `code_used`	                  | `string`  | `eq`, `gt`, `gr`, `lt`, `le`	  | `eq(code_used,2)` |
| `code_created_date`           |	`string`	| `eq`, `gt`, `gr`, `lt`, `le`	  | `eq(code_created_date,2023-11-15)` |
| `order_id`                    |	`string`  | `eq`, `like`	              | `eq(order_id,ccb13673-627c-4976-88da-f77c542b528f)`  |
| `order_customer_email`	      | `string`  | `eq`, `like`	              | `like(order_customer_email,andy*)`  |
| `order_created_date`	      |  `string`	| `eq`, `gt`, `gr`,`lt`, `le`	      |  `le(order_created_date,2023-11-15)`  | 

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","style":"form","explode":true,"schema":{"type":"string","examples":["0"]}},{"name":"page[limit]","in":"query","description":"The number of records per page.","style":"form","explode":true,"schema":{"type":"string","examples":["10"]}},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"description":"Specifies the type of the resource. The type of resource for promotions is, `promotion_codes`.","type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"array","items":{"type":"object","oneOf":[{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}],"discriminator":{"propertyName":"promotion_type","mapping":{"fixed_discount":{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"percent_discount":{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_fixed_discount":{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_percent_discount":{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},"x_for_y":{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},"x_for_amount":{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},"bundle_fixed_discount":{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},"bundle_gift":{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}}},"required":["promotion_type"],"properties":{"promotion_type":{"type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]}},"title":"Data.PromotionObject"}},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string"},"first":{"description":"Always the first page.","type":"string"},"last":{"description":"If there is only one page, it returns `null`.","type":"string"},"next":{"description":"If there is only one page, it returns `null`.","type":"string"},"prev":{"description":"If the user is on the first page, it returns `null`.","type":"string"}},"title":"Response.PageLinks"},"meta":{"title":"Response.Meta.Promotions","type":"object","properties":{"page":{"type":"object","properties":{"current":{"description":"The current page.","type":"integer"},"limit":{"description":"The maximum number of records per page for this response. You can set this value up to 100.","type":"integer"},"offset":{"description":"The current offset by number of records, not pages. Offset is zero-based.","type":"integer"},"total":{"description":"The total page count.","type":"integer"}},"title":"Response.PaginationPage"},"results":{"type":"object","properties":{"total":{"description":"The total number of results.","type":"integer"}},"title":"Response.PaginationResults"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}}}}
>
  
</StatusCodes>

---

## Get Promotion Code Exported File

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Promotion Code Exported File"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/promotions/{promotionID}/jobs/{jobID}/file"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves exported codes in a CSV format.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of a promotion."},{"name":"jobID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of a job associated with the file."},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"href":{"type":"string","description":"URL to download the CSV file."}}}}}}}}
>
  
</StatusCodes>

---

## Get Promotion Codes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Promotion Codes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/promotions/{promotionID}/codes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can use this endpoint to retrieve promotion codes. 

:::note
- The `codes.max_uses` attribute represents the maximum usage of the codes. 
- The `codes.uses` attribute represents the remaining number of times the codes can be used for the promotion.
- Codes created before April 27, 2023 will only have `codes.uses` attribute in the response body.
:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","description":"The unique identifier of the promotion.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"filter","in":"query","schema":{"type":"string"},"description":"This parameter accepts a filtering expression that uses specific operators and attributes. Promotion codes are case-insensitive.\n\nThe following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](/guides/Getting-Started/filtering#supported-characters).\n\n| Attribute | Type     | Operator    | Example        |\n|:--------- |:---------|:------------|:---------------|\n| `code`    | `string`, `number` |  `eq`, `gt`       |  `eq(code,summer2024)`, `gt(code,2024)` |\n"},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"description":"Specifies the type of the resource. The type of resource for promotions is, `promotion_codes`.","type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"array","items":{"title":"Data.PromotionsCodesObject","type":"object","properties":{"data":{"title":"Data.PromotionsCodes","type":"object","properties":{"codes":{"type":"array","items":{"title":"Data.CodeResponse","type":"object","properties":{"code":{"description":"Specifies the name of the code.","type":"string","examples":["ZXY_CBA"]},"consume_unit":{"description":"Specifies whether the code is applied to a line item or cart. The options are `per_item` or `per_cart`. The default setting is `per_cart`, which is applied at cart level. The `per_item` setting specifies how many times a buyer can use a promotion code on promotion items in a cart. For example, in a store that offers 50% off on SKU1, but limits the maximum usage of the promotion code to two, buyer can apply the promotion to SKU1 up to 2 times if cart has two quantities of SKU1. The third SKU1 is sold for regular price. The code usage is applied at checkout. You must set the automatic setting to false and create a code for this promotion to work.","type":"string","examples":["per_item"]},"user":{"description":"Specifies the users who can use the code. You can use the customer object ID or an array of customer object IDs. For more information, see the [Create a customer](/docs/customer-management/customer-management-api/create-a-customer) section. Additionally, you could pass any identifying string to the promotions service that identifies a user.","type":"string","examples":["{customerID}"]},"uses":{"description":"Specifies the maximum number of times the code can be used. If no value is set, the shopper can use the code any number of times.","type":"number","examples":[10]},"created_by":{"description":"Specifies by whom it was created.","type":"string","examples":["john.doe@company.com"]},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"Specifies the date the code was created.","type":"string","example":"2023-11-07T23:04:18.845Z"}}}}}}},"description":""}}}}}},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string"},"first":{"description":"Always the first page.","type":"string"},"last":{"description":"If there is only one page, it returns `null`.","type":"string"},"next":{"description":"If there is only one page, it returns `null`.","type":"string"},"prev":{"description":"If the user is on the first page, it returns `null`.","type":"string"}},"title":"Response.PageLinks"},"meta":{"title":"Response.Meta.Promotions","type":"object","properties":{"page":{"type":"object","properties":{"current":{"description":"The current page.","type":"integer"},"limit":{"description":"The maximum number of records per page for this response. You can set this value up to 100.","type":"integer"},"offset":{"description":"The current offset by number of records, not pages. Offset is zero-based.","type":"integer"},"total":{"description":"The total page count.","type":"integer"}},"title":"Response.PaginationPage"},"results":{"type":"object","properties":{"total":{"description":"The total number of results.","type":"integer"}},"title":"Response.PaginationResults"}}}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}}}}
>
  
</StatusCodes>

---

## Get Promotion Jobs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Promotion Jobs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/promotions/{promotionID}/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the list of jobs for a specific promotion.

In the response example, you can see the `result.generated` field, which indicates the number of codes generated during the job processing. Additionally, you may also see the optional `result.deleted` field, indicating the number of codes deleted during the job cancellation. The parameters and result objects are shown only when `job_type` is `code_generate`.

### Filtering

The following operators and attributes are available when filtering on this endpoint.

| Attribute | Type | Operator | Example |
| ----------| ----- | -------- | ------ |
| `job_type` | `string` | `eq` | `eq(job_type, code_export)` |
| `status` | `string` | `eq` | `eq(status, complete)` |

### Errors

If an error occurs during job processing, the response includes an optional error field. For example, when you `GET` promotion jobs, the following response shows the details within the error field if an error occurred during job processing.

  ```json
\{
    "data": [
        \{
            "type": "promotion_job",
            "id": "84d86114-a92d-4c34-92f1-3e36ef6cabeb",
            "promotion_id": "ad386702-e780-42c6-b190-0527ad768917",
            "job_type": "code_generate",
            "name": "job",
            "parameters": \{
                "number_of_codes": 1000,
                "consume_unit": "per_cart",
                "max_uses_per_code": 1,
                "code_length": 8,
                "code_prefix": "promo-"
            \},
            "status": "failed",
            "error": "codes limit exceeded",
            "meta": \{
                "timestamps": \{
                    "created_at": "2023-12-06T13:52:29.587Z",
                    "updated_at": "2023-12-06T13:54:49.133Z"
                \}
            \}
        \}
    ],
    "links": \{
        "current": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25",
        "first": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25",
        "last": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25",
        "prev": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25",
        "next": "https://useast.api.elasticpath.com/v2/promotions/ad386702-e780-42c6-b190-0527ad768917/jobs?page[offset]=0&page[limit]=25"
    \},
    "meta": \{
        "page": \{
            "limit": 25,
            "offset": 0,
            "current": 1,
            "total": 1
        \},
        "results": \{
            "total": 1
        \}
    \}
\}
```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of a promotion."},{"name":"filter","in":"query","required":false,"schema":{"type":"string"},"description":"Specifies the filter attributes."},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a job is created."},"type":{"description":"Always `promotion_job`.","type":"string","example":"promotion_job"},"promotion_id":{"description":"A unique ID of a promotion.","type":"string"},"job_type":{"description":"The type of job you want to run. For example, `code_generate` to generate codes or `code_export` to export codes.","type":"string"},"name":{"description":"The name of the job. The maximum length allowed is 50 characters.","type":"string"},"parameters":{"type":"object"},"status":{"description":"The status of the job. See [Overview](/docs/api/promotions/promotion-jobs).","type":"string"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The creation date of the job.","type":"string","format":"date-time"},"updated_at":{"description":"The last updated date of the job.","type":"string","format":"date-time"}}}}}},"title":"PromotionJob"}}}}}}}}}
>
  
</StatusCodes>

---

## Promotion Codes

You can apply promotions automatically to all customer carts, or you can create promotion codes that customers must enter to receive the discount. You can enable this feature by setting the automatic attribute to `false` in the promotions schema when you create a promotion. For more information, see [Create Promotion Codes](/docs/api/promotions/create-promotion-codes).

You can generate and export codes for a promotion using the bulk code generation feature, which allows you to create a large number of unique codes and export them in CSV format. For details, refer to the [Generating Bulk Codes](/docs/commerce-manager/promotions-standard/overview#generating-bulk-codes) and [Managing Export Codes](/docs/commerce-manager/promotions-standard/overview#managing-code-export) sections.

You can generate a maximum of 1000 codes for a promotion. If you need to generate more than 1000 codes, limit the promotion's duration to a maximum of 365 days from its start date. The promotion expiry date is 365 days.

With the consume unit feature, you can limit the number of usages of a code for a promotion. You must create a code for this promotion to track the usage of the promotion. The consume unit options are `per_cart` and `per_item`. For example, consider a store that offers 50% off on *SKU1*, but limits the promotion to a maximum of two usages. Under the `per_cart` setting, a shopper can buy *SKU1* twice in a separate transaction, each at a 50% discount. However, with the `per_item` setting, if a shopper buys two SKU1s in a single purchase, both items count toward the promotion's usage limit. Therefore, the shopper would use up both usages of the promotion in a single purchase.

Promotion codes can be group codes or individual codes. For example, you can offer a seasonal discount to all customers, such as *SUMMER-SALE*, or you can offer preferred customers unique discount codes. Promotion codes expire automatically at the end of the promotion period and are removed from the promotion.

When a promotion expires, the promotion codes attached to the promotion automatically become invalid. However, when you re-enable the expired promotion, the promotion codes attached to the promotion are deleted.

When you checkout a cart with an expired promotion, the expired promotion will be automatically removed from a cart and the checkout process is initiated. As a best practice, we recommend to update your cart to remove the expired promotion before initiating the checkout process.

When extending the end date of an expired promotion with over 1000 codes, you will receive an error response. See [Update a Promotion](/docs/api/promotions/update-a-promotion). In such cases, we recommend [duplicating the promotion](/docs/commerce-manager/promotions-standard/overview#duplicating-promotions), allowing you to set the new end dates and create promotion codes as needed.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Promotion Jobs

Use Jobs API to initiate a job within a promotion. Jobs operate asynchronously and have a different status based on their progress. The following are the job statuses:

- `pending`: Commerce has received the request but is currently busy processing other requests.
- `processing`: Commerce has initiated processing the job.
- `completed`: The job is successfully completed.
- `failed`: The job has failed.
- `cancelling`: The job is currently in the process of being canceled. You need to wait for the cancellation process to complete. This occurs prior to the `cancelled` status. For example, if you cancel a big `code_generate` job, it may take some time for the cancellation to complete since part of the cancellation process involves deleting the generated codes.
- `cancelled` : The job request is canceled.

![Promotion Job Statuses Workflow](/assets/job_status_workflow.png)

### Characteristics of Jobs

- You can only initiate one job at a time within a promotion. If you want to run another job for the same promotion, you must wait until the previous job is `completed` or `failed`. However, you can create new jobs for different promotions even if there are `pending` jobs in other promotions.
- If you intend to manage promotions with more than 10,000 codes per promotion, we recommend [exporting codes](/docs/api/promotions/create-a-promotion-job) for viewing purposes instead of attempting to view them within Commerce Manager. This recommendation is made due to our enforced maximum page offset limit of 10,000. Altering the page_offset_limit value poses potential performance risks to the platform.
- A `code_generate` job is initiated even if the maximum allowable number of codes for the promotion has been reached. However, when processed, this job will fail. To view the status of this failed job, you can only do so by passing [GET Jobs](/docs/api/promotions/get-promotion-jobs) request.
- A limited number of jobs can be processed at a time. Jobs are queued and processed sequentially, one after the other. You can expect a certain delay before job processing.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Promotions Standard Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/promotions/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Promotions Standard Introduction"}
>
</Heading>

Promotions Standard offer the flexibility to provide different types of discounts to all your customers or specific customers. You can apply promotions automatically to all purchases, or alternatively, create promotion codes that customers must enter to receive a discount.

You can have multiple promotions active at the same time. Promotions are active in a fixed duration, with defined start and end dates. However, you can manually stop a promotion at any time.

For testing your promotions when scheduling a future date for your shopping cart, you can use the [Preview Cart API](/docs/api/carts/create-a-cart#preview-cart).

When [Creating a Free Gift Promotion](/docs/api/promotions/create-a-promotion), set the promotion to automatic and enable the `auto_add_free_gift` feature. This way, the shopper will see the free gift in their shopping cart when the target product is added to the cart, and the discount will be applied. This eliminates the need for an additional step to apply the code for the gift discount. However, if you desire more control over when or how the free gift is added, you can choose to use a promotion code and disable the **Automatically add free gift items to the cart** toggle in Commerce Manager. See [Creating Free Gift Promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/free-gift-promotions). For a seamless process, ensure that the currencies of automatically added gift items match with those of the items that initiate free gifts. Additionally, ensure that the free gift item is within the same catalog as the eligible items.

For inventory-managed products, ensure that you have sufficient inventory available to run the promotion. If there is insufficient stock of free gift items for all eligible free products, the free gifts won't be added to the cart.

Promotions Standard can be:

- [Cart-level promotions](#cart-level-promotions): The promotion applies to the entire cart.
- [Item-level promotions](#item-level-promotions): The promotion applies to individual items in a cart.

:::note

The shipping prices do not impact eligibility for item-level and cart-level promotions.

:::

All items in the cart are eligible for cart-level promotions, even if they already have item-level promotions applied. You can select a few products and exclude them from a cart-level promotion. However, the store that uses a simple calculation method does not support promotions with the exclude setting.

### Cart-level Promotions

Cart-level promotions are applied to all items in the cart. Cart-level promotions include:

- Fixed discount: Reduces the cart total by a fixed amount, such as $5.00 off.
- Percentage discount: Reduces the cart total e by a specific percentage, such as 10% off.

The following image shows a cart before and after applying a 10% Off promotion. With the discount applied, the price for each item is reduced by 10% and the cart total reflects the reduction.

![Each item in the cart shows a price that is 10% less than the catalog price.](/assets/promotions-cart-10-percent-off.png)

All items in the cart are eligible for cart-level promotions, even if they already have item-level promotions applied. You can select a few products and exclude them from a cart-level promotion. However, the store that uses a [simple calculation method](https://elasticpath.dev/guides/How-To/Carts/calculate-totals#simple-calculation-method) does not support promotions with the `exclude` setting.

### Item-level Promotions

Item-level promotions are applied to each item that qualifies for the promotion. In a shopping cart, the price of each item reflects the discount applied to each item. With the `max_applications_per_cart` setting, you can limit the number of purchases of an item at the sale price in a cart. For more information, see the Promotions API section.

Item-level promotions include the following promotion types:

- X for Y: Offers bulk discount based on unit price, such as 2-for-1 sales.
- X for amount: Offers a bulk discount based on a fixed price, such as 3-for-$20 sales.
- Bundle: Offers bulk discount when selected products are purchased together. For example, Buy any two items from the list for $100.
- Item fixed discount: Reduces the price of multiple items by a fixed amount, such as $5.00 off.
- Percentage item discount: Reduces the product price for multiple items by a specific percentage, such as 10% off. You can also count the number of usages of the promotion per SKU item and limit the usage of the promotion per item. For example, if the usage of the promotion is limited to ten and the shopper purchases two of the same item and three of the another item, five uses of the promotion is deducted from the total usage limit.
- Free Gift: Offers a free item when a specific product or a group of products are purchased.

  :::caution

  - Item-level promotions are only supported by the line calculation method. For more information about this method, see the [Calculation Method](/docs/api/settings/settings-introduction#calculation-method) section.
  - The `max_discount_value` setting specifies the maximum possible discount for the cart. To avoid the conflict with the promotions and the promotion to work, we recommend not to use this setting for the following promotions:

    - Cart-level fixed discount
    - Item fixed discount
    - X for Y discount
    - X for amount discount
    - Bundle
    - Free gift

  - The `max_applications_per_cart` setting, which specifies the maximum number of applications of a promotion per cart, is applicable to line-item promotions only. For example, in a store that offers *buy SKU1 get a free gift* promotion with maximum application per cart set to one, the buyer can only use the free gift promotion once per cart. If maximum application per cart is not set, the buyer can use the promotion multiple times. You can also set maximum application per cart to zero to remove any usage limit.
  - The `exclude` array consists of productIDs or SKUs of products to be excluded from the cart-level promotions, such as `fixed_discount` and `percent_discount`. However, the stores that use simple calculation method do not support excluding products from promotions.
  - Already existing promotions created before September 28, 2022 will not have `created_by` and `updated_by` attributes in their response body.

  :::

You can create codes for a promotion so that customers receive the discount only when the code is provided.

### Multiple promotions for the same SKU

You can have multiple promotions for the same SKU. However, each instance of the SKU in the cart is eligible for only one item-level promotion.

:::note

The promotions are applied in the order of date of creation of the promotions. The oldest promotion is applied first and the newest promotion is applied last. For each instance of a SKU that matches the criteria in the oldest promotion, the promotion is applied. For the remaining instances of the SKU, each instance is compared to the criteria for the next oldest promotion.

:::

For example, a cart consists of 1 *BestEver Coffee Maker* and 2 *BestEver Coffee Grinders*. The following promotions are available and applied automatically without a code:

- An existing *BestEver Coffee Maker* + *Grinder* bundle promotion for $200.00. The bundle discount is distributed among the items in the bundle depending on the price of each item.
- A newly added *BestEver Coffee Grinders* 10% Off percentage item discount promotion.

In this example, *BestEver Coffee Maker* costs $150 and *BestEver Coffee Grinder* costs $100. The promotions work in the following order:

1. The $50 bundle discount is distributed among the items depending on the cost. In this example, the cost proportion of products is 3:2 and the *BestEver Coffee Maker* gets $30 discount and *BestEver Coffee Grinder* gets $20 discount.
2. The second promotion is applied to the remaining *BestEver Coffee Grinders* item, and the price is reduced to $90.
3. The cart total after both discounts is $290 instead of $350.

### Understanding how Promotions work with Bundles

#### Discounting Promotion Bundles

Bundles offer a bulk discount when selected products are purchased together. For example, for a bundle promotion, (SKU1 or SKU2 ) + SKU3, the promotion is applied if the bundle includes either SKU1 and SKU3 or SKU2 and SKU3. This setup encourages the purchase of multiple items together at a discounted rate.

#### Discounting Product Bundles via promotions

For both Cart-level promotions and Item-level promotions, discounts are applied at the bundle level that can have fixed bundle price or automatic/cumulative pricing.

It is important to note that promotions do not apply to components within a bundle even if the individual item within the components qualifies for promotion. See the following examples:

  - **Example 1**: Consider that Playtend Games offers a bundle that includes a game console, the Playtend Invaders Game, and the Invaders Controller. If there is an existing Item Percent Discount for the Playtend Invaders Game when sold separately, this discount will not apply when the game is part of the bundle. This ensures that the bundle pricing strategy is maintained.
  - **Example 2**: In the case of Attribute-based promotions, consider a bundle that consists of *Item A* with attribute *Brand A* and *Item B* with attribute *Brand B*. If *Item A* with attribute *Brand A* qualifies for Item Percent Discount promotion, this discount is not applied to the bundle since the *Item A* is a component item within the bundle.

To learn how to create a bundle, see [Create a Bundle](/docs/api/pxm/products/create-product).

### Condensed Promotion

A condensed promotion is essentially an object that contains specific meta information about a promotion applied to the cart or order.

Condensed promotions can be retrieved from the following endpoints:

- [Get a Cart](/docs/carts-orders/Includes#get-retrieve-promotions-from-a-cart): This endpoint displays cart-level condensed promotions within the included object. If `?include=items` is specified, the included object also contains cart item-level promotions. The relationships field at the cart level has a promotions section only when `?include=promotions` is specified.
- [Get Cart Items](/docs/carts-orders/Includes#get-retrieve-promotions-from-cart-items): This endpoint shows both cart-level and item-level discounts in a condensed format within the included object.
- [Get an Order](/docs/carts-orders/Includes#get-retrieve-promotions-from-an-order): This endpoint displays order-level condensed promotions within the included object.
- [Get Order items](/docs/carts-orders/Includes#get-retrieve-promotions-from-order-items): This endpoint displays both order-level and item-level promotions in the included object.

This applies to both Promotions Standard and [Rule Promotions](/docs/promotions-builder/overview).

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: 
  
    URL: [https://elasticpath.com](https://elasticpath.com)
  

  
    License
  
    MIT

---

## Promotions Standard

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Update a Promotion

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Promotion"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/promotions/{promotionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to update a specific promotion.

:::note

  You can re-enable an expired promotion by updating the end date to a future date. However, when you enable a promotion again, all codes previously attached to it are deleted to make sure that duplicate promotion codes do not exist on different promotions.

:::

### Errors

When extending the end date of an expired promotion with over 1000 codes, you will receive the following error response. In such cases, we recommend duplicating the promotion, allowing you to set the new end dates and create promotion codes as needed.

```json
{
    "errors": [
        {
            "status": 422,
            "source": "request",
            "title": "Unprocessable Entity",
            "detail": ""
        }
    ]
}
```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"promotionID","in":"path","description":"The unique promotion identifier.","required":true,"style":"simple","schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"type":"object","oneOf":[{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}],"discriminator":{"propertyName":"promotion_type","mapping":{"fixed_discount":{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"percent_discount":{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_fixed_discount":{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_percent_discount":{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},"x_for_y":{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},"x_for_amount":{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},"bundle_fixed_discount":{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},"bundle_gift":{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}}},"required":["promotion_type"],"properties":{"promotion_type":{"type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]}},"title":"Data.PromotionObject"}]}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","headers":{},"content":{"application/json":{"schema":{"allOf":[{"description":"Specifies the type of the resource. The type of resource for promotions is, `promotion_codes`.","type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","oneOf":[{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}],"discriminator":{"propertyName":"promotion_type","mapping":{"fixed_discount":{"title":"Data.CartFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"percent_discount":{"title":"Data.CartPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.PercentageAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.PercentageAndCurrency","type":"object","required":["percentage","currency"],"properties":{"percentage":{"description":"Specifies the discount percentage of the cart total value. For example, 10 represents 10% discount of the cart value of $100. You can add up to six decimal places for the discount percentage to be applied for the promotion.","type":"number"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_fixed_discount":{"title":"Data.ItemFixedDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}}]}}}]},"item_percent_discount":{"title":"Data.ItemPercentDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.Percent","type":"object","required":["percent"],"properties":{"percent":{"description":"Specifies the discount percentage to be applied to the targeted SKU price. For example, 10% discount on a product SKU priced at $100. You can specify the discount percentage with up to six decimal places.","type":"integer"}}}]}}}]},"x_for_y":{"title":"Data.XForYDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.TargetAttributes","type":"object","properties":{"target_attributes":{"type":"array","items":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be included in a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field to be included in a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.type`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}},{"title":"Data.Promotions.Schema.YValue","type":"object","required":["y"],"properties":{"y":{"description":"Specifies the Y value for the promotion.","type":"integer"}}}]}}}]},"x_for_amount":{"title":"Data.XForAmountDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Targets","type":"object","properties":{"targets":{"description":"Specifies the product SKUs or unique identifiers of the products included in the promotion. Set \"targets:all\" if you want to apply the promotion to all SKUs. Leaving this field empty might cause errors. You need to define `schema.targets`, `schema.target_nodes` or `schema.target_attributes`, or all three of them to qualify for this promotion.","type":"array","items":{"type":"string"},"examples":["sku1"]}}},{"title":"Data.Promotions.Schema.TargetNodes","type":"object","properties":{"target_nodes":{"description":"Specifies the unique identifiers of the nodes to be applied for the promotion in addition to the product SKUs applied in targets. You can also define `schema.target_nodes` without defining the `schema.targets` if the promotion is intended for a certain node. You cannot define \"targets\":\"all\" and `schema.target_nodes` within the same schema. This will result in a validation error.","type":"array","items":{"type":"string","examples":["ff7d62d4-740c-43ac-97cd-a7b0c32221c2"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Exclude","type":"object","properties":{"conditions":{"type":"object","title":"Data.Conditions","properties":{"or":{"type":"array","items":{"type":"object","properties":{"and":{"type":"array","items":{"oneOf":[{"title":"Data.AttributeObject","type":"object","properties":{"attribute":{"type":"object","properties":{"template":{"description":"Specifies the name of the template slug to be excluded from a promotion.","type":"string","examples":["products(shoes)"]},"field":{"description":"Specifies the unique slug identifier for the field excluded from a promotion.","type":"string","examples":["brand"]},"type":{"description":"Specifies the type of the field, such as `string`, `integer`, `boolean`, `float`, or `date`.","type":"string","examples":["string"]},"value":{"description":"Specifies the value of the field that was specified in the `attributes.field`. For example, you can specify any color in the value if you indicate color in the `attributes.field`.","type":"string","examples":["adidas"]}}}}},{"title":"Data.NodesObject","type":"object","properties":{"node":{"type":"object","properties":{"values":{"description":"Specifies unique identifiers of the nodes to be excluded from the promotion.","type":"array","items":{"type":"string","description":"node or hierarchy ids","examples":["19650d2e-7e9d-496a-8658-5107dd8ad803","fe0cff14-1b7e-4abf-88db-cd0fd6a3ec5b"]}}}}}}]}}}}}}}}},{"title":"Data.Promotions.Schema.XValue","type":"object","required":["x"],"properties":{"x":{"description":"Specifies the X value for the promotion.","type":"integer"}}}]}}}]},"bundle_fixed_discount":{"title":"Data.FixedBundleDiscountPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.AmountAndCurrencyArray","type":"object","required":["currencies"],"properties":{"currencies":{"type":"array","items":{"title":"Data.Promotions.Schema.Currencies.AmountAndCurrency","type":"object","required":["amount","currency"],"properties":{"amount":{"description":"Specifies the fixed discount amount to be applied to the cart. For example, $10 off the total amount in the cart.","type":"integer"},"currency":{"description":"Specifies a three-letter currency code. For example, USD.","type":"string"}}}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}}]}}}]},"bundle_gift":{"title":"Data.FreeGiftPromotion","allOf":[{"title":"Data.Promotions","type":"object","required":["type","id","name","description","automatic","enabled","promotion_type","schema","start","end"],"properties":{"type":{"description":"Specifies the type of the resource. The type of resource for promotions is `promotion`.","type":"string","const":"promotion"},"id":{"type":"string","format":"uuid","readOnly":true},"name":{"description":"Specifies a name for the promotion.","type":"string","examples":["Buy SKU1 and SKU2 to get free gift"]},"description":{"description":"Specifies a description for the promotion.","type":"string","examples":["SKU1 and SKU2 for free gift"]},"promotion_type":{"description":"Specifies the type of the promotion.","type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]},"enabled":{"description":"Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`.","type":"boolean","examples":[true]},"automatic":{"description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is to `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the Create Promotion Codes section.","type":"boolean","examples":[true]},"start":{"description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format.","type":"string","examples":["2020-01-01"]},"end":{"description":"Specifies the end date and time of the promotion or the end date of the promotion.","type":"string","examples":["2100-01-01"]},"min_cart_value":{"description":"Specifies an array of currency-value objects, `min_cart_value[].currency` and `min_cart_value[].amount`, that provides the minimum cart value required for the promotion to apply. You can add one or several value specifications in different currencies. Do not use `max_discount_value` for Cart Fixed Discount promotion and Item Fixed Discount promotion. If `max_discount_value` is greater than the `fixed_discount` value, the `fixed_discount` value is applied; otherwise the `max_discount value` is applied.","type":"object","examples":[{"amount":1000,"currency":"USD"}]},"max_applications_per_cart":{"description":"Specifies the maximum number of application of a promotion per cart.","type":"number","examples":[0]}}},{"type":"object","properties":{"schema":{"allOf":[{"title":"Data.Promotions.Schema.TargetCatalogs","type":"object","properties":{"target_catalogs":{"description":"Specifies the unique identifiers of the catalogs to be applied for this promotion. If you do not set this parameter, promotion will be applied to all catalogs.","type":"array","items":{"type":"string","examples":["baff37e6-1c9b-449d-852c-80ec4d0e39c6"]}}}},{"title":"Data.Promotions.Schema.Requirements","type":"object","required":["requirements"],"properties":{"requirements":{"type":"array","items":{"title":"Data.Promotions.Schema.Requirement","type":"object","required":["targets","quantity"],"properties":{"targets":{"description":"Specifies an array of required product SKUs or IDs for the bundle discount promotion.","type":"array","items":{"type":"string"}},"quantity":{"description":"Specifies the quantities of products to be applied for the promotion.","type":"integer"}}}}}},{"title":"Data.Promotions.Schema.Gifts","type":"object","required":["gifts"],"properties":{"gifts":{"description":"Specifies all the gift items that a shopper can avail when they qualify for the promotion. The gift quantity applies to each specified item. For example, if the promotion includes `giftA` and `giftB`, shopper can avail both the gifts if the cart qualifies for the gift promotion. If the cart qualifies for two gift promotions, the shopper can use two `giftA` and two `giftB`.","type":"array","items":{"type":"string"}},"auto_add_free_gift":{"description":"When set to `true`, free gift items are automatically added to the shopping cart for all the eligible products. Default is `false`.","type":"boolean"}}}]}}}]}}},"required":["promotion_type"],"properties":{"promotion_type":{"type":"string","enum":["fixed_discount","percent_discount","item_fixed_discount","item_percent_discount","x_for_y","x_for_amount","bundle_fixed_discount","bundle_gift"]}},"title":"Data.PromotionObject"}}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"array","properties":{"detail":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"}},"title":"Response.Error"},"example":[{"errors":[{"status":401,"title":"Unauthorized"}]}]}}}}}
>
  
</StatusCodes>

---

## Anonymize Rule Promotion Usages

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Anonymize Rule Promotion Usages"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/rule-promotions/usages/anonymize"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Anonymizes user-related data in Rule Promotion usage records. 
This operation is typically used for GDPR compliance or privacy-related requests.

- This process replaces identifiable user data with anonymized placeholders.
- Affects all recorded promotion usages where customer data is stored.
- Does not impact historical transaction records or applied discounts.

A successful request returns a `200 OK` response with the anonymized usage records.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"},"description":"The unique identifiers of the usages to be anonymized.\nMultiple usage IDs can be provided to anonymize in bulk.\n"}}}},"required":["data"]},"example":{"data":{"usage_ids":["ca4385ec-7fb2-4a95-8690-f752c508d68a","d4e5f6g7-h8i9-0j1k-2l3m-4n5o6p7q8r9s"]}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Represents a single rule promotion usage record.","properties":{"id":{"type":"string","description":"The unique identifier of the usage record."},"order_id":{"type":["string","null"],"description":"The associated order ID, if applicable."},"code_id":{"type":"string","description":"The unique identifier of the promotion code."},"code":{"type":"string","description":"The promotion code used."},"times_used":{"type":"integer","description":"The number of times the promotion code has been used."},"used_on":{"type":"string","format":"date-time","description":"The timestamp when the promotion was applied."},"customer_id":{"type":["string","null"],"description":"The customer identifier who used the promotion, if applicable."},"account_id":{"type":["string","null"],"description":"The account identifier associated with the promotion usage, if applicable."},"customer_email":{"type":["string","null"],"description":"The email of the customer who used the promotion, if applicable."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"updated_at":{"type":"string","format":"date-time","description":"The timestamp when the usage record was last updated."}}}}},"updated_by":{"type":"string","description":"Identifier of the user or system that last updated the record."},"anonymized":{"type":"boolean","description":"Indicates whether the usage record has been anonymized."}},"title":"RulePromotionUsage"}}}},{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"}],"example":{"data":[{"id":"ca4385ec-7fb2-4a95-8690-f752c508d68a","order_id":"8edd5ca8-39b7-468d-aea9-a470690ca98d","code_id":"00fc633b-9932-4e18-b122-fd5c3173caa3","code":"node1off","times_used":1,"used_on":"2023-06-19T18:05:20.846Z","customer_id":"9ef25142-d67a-41d3-99b2-4d30aeef6c9d","customer_email":"**","meta":{"timestamps":{"updated_at":"2023-06-19T18:05:39.141Z"}},"updated_by":"Key-2439657140697170361","anonymized":true}]}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"example":{"errors":[{"status":400,"title":"Invalid Request","detail":"The request payload is malformed or missing required fields."}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"example":{"errors":[{"status":401,"title":"Unauthorized","detail":"Authentication credentials were missing or incorrect."}]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"example":{"errors":[{"status":404,"title":"Usages Not Found","detail":"Some usage IDs could not be found.","meta":{"usage_ids":["invalid-usage-id-1","invalid-usage-id-2"]}}]}}}}}}
>
  
</StatusCodes>

---

## Cancel a Rule Promotion Job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cancel a Rule Promotion Job"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/rule-promotions/{uuid}/jobs/{job-uuid}/cancel"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Cancels an asynchronous job for a rule promotion if its status is `pending` or `processing`.

- Only jobs that have not yet completed can be canceled.
- Once canceled, no further processing occurs, and partially completed results may be deleted.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."},{"name":"job-uuid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the job to be canceled."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully Canceled the Rule Promotion Job","content":{"application/json":{"schema":{"type":"object","description":"Promotion job response","properties":{"data":{"allOf":[{"type":"object","properties":{"job_type":{"description":"The type of job to run. For example, `code_generate` to generate codes or `code_export` to export codes.","type":"string","enum":["code_generate","code_export"],"x-enumDescriptions":{"code_generate":"Generates a batch of unique promotion codes with specified parameters such as code length, prefix, and usage limits.","code_export":"Exports all existing promotion codes for the promotion as a downloadable CSV file."}},"name":{"type":"string","description":"Represents the name of the job. The maximum allowed length is 50 characters.","maxLength":50},"parameters":{"type":"object","properties":{"number_of_codes":{"type":"integer","description":"Specifies the number of codes to be generated.","maximum":1000},"max_uses_per_code":{"type":"integer","description":"Specifies the maximum number of usages per code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times."},"consume_unit":{"type":"string","enum":["per_application","per_checkout"],"description":"Specifies whether the promotion code is consumed per application or per checkout. This determines how usage limits are applied when a code is used multiple times.\n","x-enumDescriptions":{"per_application":"The code is consumed per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage.","per_checkout":"The code is consumed once per checkout, regardless of the number of items in the cart or how many times the promotion is applied within that checkout."}},"code_prefix":{"type":"string","description":"Prefix for generated promotion codes (e.g., `SUMMER-`)."},"code_length":{"type":"integer","description":"Code length.","maximum":16,"minimum":8,"default":8}}},"id":{"type":"string","description":"A unique ID generated when a job is created."},"type":{"type":"string","const":"promotion_job"},"rule_promotion_id":{"description":"A unique ID of a promotion.","type":"string"}},"title":"PromotionJob"},{"type":"object","properties":{"status":{"description":"The status of the job.","type":"string","enum":["pending","processing","completed","failed","cancelling","cancelled"],"x-enumDescriptions":{"pending":"Commerce Cloud has received the request but is currently busy processing other requests.","processing":"Commerce Cloud has initiated processing the job.","completed":"The job is successfully completed.","failed":"The job has failed.","cancelling":"The job is currently in the process of being canceled. You need to wait for the cancellation process to complete.","cancelled":"The job request is canceled."}},"error":{"description":"The error encountered during job execution, if applicable.","type":"string"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The creation date of the job.","type":"string","format":"date-time"},"updated_at":{"description":"The last updated date of the job.","type":"string","format":"date-time"}}}}},"result":{"type":"object","description":"Represents the result of a promotion job, including the number of generated and deleted promotion codes.\n\n- `generated`: Total number of successfully generated codes.\n- `deleted`: Number of codes that were deleted during job cancellation, if applicable.\n","properties":{"generated":{"type":"integer","description":"Number of successfully generated promotion codes.","example":1000},"deleted":{"type":["integer","null"],"description":"Number of codes deleted due to job cancellation.","example":50}},"title":"GenerateResult"}}}],"title":"PromotionJobResponse"}}},"examples":{"PromotionJobCancellingResponse":{"summary":"Successful Cancellation Request for a Rule Promotion Job","description":"This response indicates that the **job cancellation request was successfully submitted**, and the job is now in the `\"cancelling\"` state.\n\n- The job has entered the **cancelling state**, meaning the system is stopping it.\n- To check the job's final status, use the **Get Rule Promotion Jobs** endpoint.\n- If the job successfully cancels, it will transition to `\"cancelled\"`.\n- If cancellation fails (e.g., the job completes before being stopped), it may remain `\"completed\"`.\n","value":{"data":{"type":"promotion_job","id":"9bc1391c-1b65-419e-940e-66ed86c07001","rule_promotion_id":"8c150382-b258-4c88-a2d4-b9ea0be74a07","job_type":"code_generate","name":"Demo bulk code generate","parameters":{"number_of_codes":100,"max_uses_per_code":1,"consume_unit":"per_checkout","code_prefix":"summer-","code_length":8},"status":"cancelling","meta":{"timestamps":{"created_at":"2024-12-03T23:31:40.962680423Z","updated_at":"2024-12-03T23:31:40.962680423Z"}}}}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":"422"},"title":{"type":"string","example":"Unprocessable Entity"},"detail":{"type":"string","example":"Only pending or processing jobs can be cancelled."}}}}}},"examples":{"CannotCancelCompletedJobError":{"summary":"Error When Attempting to Cancel a Job That Is Not Pending or Processing","description":"This error occurs when a **job cancellation request** is made for a job that **is not in a `pending` or `processing` state**.\n\n**Possible Causes:**\n- Attempting to cancel a job that has already **completed**, **failed**, or was **previously cancelled**.\n- The job may have already transitioned out of `pending` or `processing` by the time the request was made.\n","value":{"errors":[{"status":"422","title":"Unprocessable Entity","detail":"Only pending or processing jobs can be cancelled."}]}}}}}}}}
>
  
</StatusCodes>

---

## Create Rule Promotion Codes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Rule Promotion Codes"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/rule-promotions/{promotionID}/codes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates new promotion codes for a specific rule promotion, allowing customers to redeem discounts based on predefined conditions.

- Supports  bulk creation of multiple promotion codes in a single request.
- Each code can have individual usage limits.
- Can optionally assign codes to specific users to enforce targeted promotions.
- The promotion codes are case-insensitive.

:::note

Regarding first time shopper limitations:
- Orders without payment transactions do not count as completed purchases.
- Canceling or refunding an order does not reinstate first-time shopper status.
- A first-time shopper coupon code cannot have limited uses or be assigned to specific users, meaning the code cannot be restricted by the number of times it can be used or tied to a specific customer ID.

:::

A successful request returns a `201 Created` response with details of the generated promotion codes.

### Duplicate Codes
Duplicate promotion codes **are supported across different promotions** in the store, regardless of their statuses and validity dates. However, **duplicate codes cannot be created within the same promotion**.
This means that shoppers can apply a single coupon code to trigger multiple promotions if those promotions share common coupon codes. 

Codes that share the same name can serve different purposes.  For example, one code may have `per_application` with a limited number of uses, while another identical code can have `per_checkout` with unlimited use.

**Duplicate Code Handling:**
- If a duplicate code is detected **within the same promotion**, the request will return a `422 Duplicate code` error.
- When creating duplicate codes, a message appears with the successful response indicating the duplication.

Please refer to the **OpenAPI examples** section on this page for sample request structures.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"promotion_codes"},"codes":{"type":"array","description":"Specifies the code details in an array of objects.","items":{"type":"object","properties":{"code":{"type":"string","description":"Specifies the string to use as a code for the promotion."},"uses":{"type":"integer","description":"Specifies the number of times the code can be used. If no value is set, the customer can use the code any number of times."},"user":{"type":"string","description":"Specifies the customer ID of the shopper who can use the code. For more information, see the [Create a customer](/docs/customer-management/customer-management-api/create-a-customer) section."},"consume_unit":{"type":"string","enum":["per_application","per_checkout"],"description":"Specifies whether the code is consumed per application or per checkout. With `per_checkout`, the code is used once for each checkout, regardless of the number of items in the cart. When set to `per_application`, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point.\n"},"max_uses_per_shopper":{"type":"object","description":"Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper.","properties":{"max_uses":{"type":"integer","description":"Sets max number of times the code can be used by a shopper. NOTE - This cannot be set with `per_application` consume unit."},"includes_guests":{"type":"boolean","default":false,"description":"The flag to include guest shoppers for the discount with max use restriction. **If this field is provided, the max_uses value is required.** When set to `true`, guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code. When set to `false`, guest shoppers cannot use the promo code, even if the cart has an associated guest email."}},"title":"MaxUsesPerShopper"},"is_for_new_shopper":{"type":"boolean","description":"A flag indicating whether the coupon is for first-time shoppers. If set to `true`, the discount will only apply if the shopper has never made a payment on any order in the store. If set to `false` or left unset, it will be a regular discount that applies to all shoppers. When this flag is set to `true`, the coupon cannot have usage limitations or be assigned to specific users."}}}}}}},"title":"PromotionCodesRequest"},"examples":{"CreateCodes":{"summary":"Create Rule Promotion Codes","value":{"data":{"type":"promotion_codes","codes":[{"code":"spring2024"},{"code":"summer2024","consume_unit":"per_checkout"},{"code":"summer2024_limited","consume_unit":"per_application","uses":5},{"code":"summer2024_memberOnly","consume_unit":"per_application","uses":1,"user":"vip_shopper@email.com"}]}}},"SingleUsePerShopperIncludingGuests":{"summary":"Create a Promotion Code Usable Once Per Shopper, Including Guest Shoppers with Emails Associated with their Carts","value":{"data":{"type":"promotion_codes","codes":[{"code":"one_per_shopper","consume_unit":"per_checkout","max_uses_per_shopper":{"includes_guests":true,"max_uses":1}}]}}},"MaxUsesLimitWithPerShopperRestriction":{"summary":"Create a Promotion Code with a Total Usage Limit and Per Shopper Restriction","description":"Create a promotion code that allows up to **10 total uses** and allows each individual shopper to use the code **once**.\n\n- The `uses` field is set to `10`, meaning the promotion code can be redeemed a maximum of **10 times across all shoppers**.\n- The `max_uses_per_shopper` field sets `max_uses: 1`, ensuring **each shopper can only redeem the code once**.\n- The `includes_guests` field is set to `true`, allowing **both registered and guest shoppers** to use the promotion code.\n- The `consume_unit` is set to `per_checkout`, meaning the code is **consumed once per successful checkout**.\n\nThis setup is useful for **one-time promotions** where a **limited number of shoppers can redeem the code** but prevents any single shopper from claiming multiple redemptions.\n","value":{"data":{"type":"promotion_codes","codes":[{"code":"one_time_use","consume_unit":"per_checkout","uses":10,"max_uses_per_shopper":{"includes_guests":true,"max_uses":1}}]}}},"MaxUsesForSpecificShopper":{"summary":"Limit Promotion Code Usage to a Specific Shopper","description":"Create a promotion which **limits the maximum usage of a promotion code to a specific shopper** based on their `customerID`.\n\n- The `uses` field is set to `1`, meaning **this promotion code can only be used once by the identified shopper**.\n- The `user` field is set to `customer-id-123`, ensuring the **code is only valid when the cart is checked out by the specified customer**.\n- The `consume_unit` is set to `per_checkout`, meaning the code is **redeemed upon a successful checkout**.\n\n**Important Notes:**\n- This method is useful for **targeted, personalized promotions** where only a specific shopper should receive the discount.\n- The promotion code **cannot be used by any other shopper**.\n- **Account user IDs are currently not supported**.\n\nThis setup is ideal for **single-use, customer-specific promotions**, such as loyalty rewards or personalized discount offers.\n","value":{"data":{"type":"promotion_codes","codes":[{"code":"one_per_shopper","consume_unit":"per_checkout","uses":1,"user":"customer-id-123"}]}}},"MaxUsesForSpecificRegisteredShopper":{"summary":"Limit Promotion Code Usage to a Specific Registered Shopper","description":"This example demonstrates how to **restrict a promotion code to a specific registered shopper** using their `customerID`, with a limit on how many times they can redeem the code.\n\n- The `user` field is set to `customer-id-123`, ensuring **only the specified shopper can use the promotion code**.\n- The `max_uses_per_shopper.max_uses` field is set to `1`, meaning **this shopper can only redeem the code once**.\n- The `max_uses_per_shopper.includes_guests` field is set to `false`, meaning **guest shoppers cannot use this code**.\n- The `consume_unit` is set to `per_checkout`, meaning **the code is consumed once per successful checkout**.\n\n**Key Differences from Other Shopper-Specific Limits:**\n- Unlike a `uses: 1` setup, which sets a global limit for the code, this method **explicitly enforces per-shopper usage limits**.\n- This approach is ideal for **exclusive promotions targeting specific registered shoppers**, ensuring that only they can redeem the discount and preventing usage by guest shoppers.\n- **Account user IDs are currently not supported**.\n\nThis setup is useful for **member-only discounts, personalized promotional offers, or exclusive VIP rewards**.\n","value":{"data":{"type":"promotion_codes","codes":[{"code":"one_per_shopper","consume_unit":"per_checkout","user":"customer-id-123","max_uses_per_shopper":{"includes_guests":false,"max_uses":1}}]}}},"FirstTimeShopperCodeRequest":{"summary":"Create a Promotion Code for First-Time Shoppers","description":"Create a **promotion code that is only applicable to first-time shoppers**.  Here, the `is_for_new_shopper` field is set to `true`, indicating that **only first-time shoppers can use this code**.\n\n**Important Notes:**\n- Promotion codes with `is_for_new_shopper: true` **cannot have usage limits** (`uses`) or be assigned to specific users.\n- If usage limits or shopper assignments are included, a **400 Invalid Code error** will be returned.\n","value":{"data":{"type":"promotion_codes","codes":[{"code":"first_time","is_for_new_shopper":true}]}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","const":"promotion_codes"},"code":{"type":"string"},"uses":{"type":"integer"},"user":{"type":"string"},"consume_unit":{"type":"string","enum":["per_application","per_checkout"]},"max_uses":{"type":"integer"},"max_uses_per_shopper":{"type":"object","description":"Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper.","properties":{"max_uses":{"type":"integer","description":"Sets max number of times the code can be used by a shopper. NOTE - This cannot be set with `per_application` consume unit."},"includes_guests":{"type":"boolean","default":false,"description":"The flag to include guest shoppers for the discount with max use restriction. **If this field is provided, the max_uses value is required.** When set to `true`, guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code. When set to `false`, guest shoppers cannot use the promo code, even if the cart has an associated guest email."}},"title":"MaxUsesPerShopper"},"is_for_new_shopper":{"type":"boolean"}},"title":"CreatePromotionCodeResponse"}},"messages":{"type":"array","items":{"type":"object","properties":{"source":{"type":"object","description":"Information about the affected promotion codes.","properties":{"type":{"type":"string","const":"promotion_codes","description":"Indicates that the affected entity is a promotion code."},"codes":{"type":"array","description":"A list of promotion codes that triggered the message.","items":{"type":"string","example":"spring2024"}}}},"title":{"type":"string","description":"A brief title summarizing the message.","example":"Duplicate code names"},"description":{"type":"string","description":"A detailed explanation of the message.","example":"Code names duplicated in other promotions"}},"title":"PromotionCodeMessage"}}},"title":"CreatePromotionCodesResponse"},"examples":{"PromotionCodeCreatedResponse":{"summary":"Response When a Promotion Code is Successfully Created","value":{"data":[{"id":"8a1c73bc-7c15-41c3-a3ed-a0aa398c3984","code":"one_per_shopper","user":"5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e","max_uses_per_shopper":{"max_uses":1,"includes_guests":false},"consume_unit":"per_checkout"}]}},"FullyConsumedPromotionCodeResponse":{"summary":"Response When a Promotion Code Has Been Fully Used","description":"Response indicating that a **promotion code has already been fully consumed** by the shopper and is no longer valid for use.\n\n- The `source.id` field provides the unique identifier of the promotion.\n- The `source.code` field specifies the exact promotion code that has been fully consumed.\n- The `title` field (`\"Fully Consumed\"`) serves as a user-friendly summary of the issue.\n- The `description` field provides a clear explanation: `\"You've already fully consumed this promotion code\"`.\n\nThis response is useful for handling **errors when applying promotion codes**, ensuring that customers receive **clear feedback** if they attempt to reuse a code that has reached its usage limit.\n","value":{"messages":[{"source":{"type":"promotion_codes","id":"38861a5c-81bb-43bc-8934-e30cde108579","code":"one_per_shopper"},"title":"Fully Consumed","description":"You've already fully consumed this promotion code"}]}},"DuplicateCodeNameResponse":{"summary":"Message Response When Creating a Duplicate Promotion Code Name","value":{"messages":[{"source":{"type":"promotion_codes","codes":["duplicate-code"]},"title":"Duplicate code names","description":"Code names duplicated in other promotions"}]}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","example":400},"source":{"type":"string","example":"data.codes.0.max_uses_per_shopper"},"title":{"type":"string","example":"missing_dependency"},"detail":{"type":"string","example":"Has a dependency on max_uses"}}}}}},"examples":{"MissingMaxUsesDependencyError":{"summary":"Error When `max_uses_per_shopper.includes_guests` is Provided Without `max_uses`","description":"This error occurs when `max_uses_per_shopper.includes_guests` is provided **without specifying** `max_uses`.\n","value":{"errors":[{"status":400,"source":"data.codes.0.max_uses_per_shopper","title":"missing_dependency","detail":"Has a dependency on max_uses"}]}},"FirstTimeShopperCodeError":{"summary":"Error When Setting Usage Limits While Assigning First-Time Shopper Codes","description":"This error occurs when a **first-time shopper promotion code** is created **with restricted uses (`uses`) or assigned to specific users (`user`)**.\n","value":{"errors":[{"status":400,"source":"","title":"Invalid Code","detail":"Code - first_time_uses can't have limited uses or assigned to users since it's for first-time shoppers."}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":"422"},"source":{"type":"string","example":""},"title":{"type":"string","example":"Unsupported consume unit"},"detail":{"type":"string","example":"Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features."}}}}}},"examples":{"UnsupportedConsumeUnitError":{"summary":"Error When `max_uses_per_shopper.max_uses` is Used with `per_application`","description":"This error occurs when `max_uses_per_shopper.max_uses` is set while using `consume_unit: per_application`, which is not supported.\n","value":{"errors":[{"status":"422","source":"","title":"Unsupported consume unit","detail":"Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features."}]}},"NoCodesAllowedForAutomaticPromotion":{"summary":"Error When Attempting to Create Promotion Codes for Automatic Promotions","value":{"errors":[{"status":"422","title":"No codes allowed","detail":"Cannot add codes to automatic promotion"}]}},"DuplicatePromotionCodeError":{"summary":"Error When Creating a Promotion Code That Already Exists","description":"This error occurs when attempting to create a promotion code that already exists within the same Rule Promotion.\n","value":{"errors":[{"status":"422","title":"Duplicate code","detail":"Promotion code already in use"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Rule Promotion Job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Rule Promotion Job"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/rule-promotions/{uuid}/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates an asynchronous job for a specific Rule Promotion. Jobs are used to generate or export promotion codes in bulk.

The following job types are supported:
- **`code_generate`**: Generates a batch of unique promotion codes.
- **`code_export`**: Exports all existing promotion codes as a downloadable CSV file.

Job processing occurs asynchronously. The job request is queued, and its status must be checked separately.

### Job Processing Status
Jobs can have the following statuses:
- `pending`: Job is in the queue, waiting to be processed.
- `processing`: Job is actively being processed.
- `completed`: Job completed successfully.
- `failed`: Job encountered an error and did not complete.
- `cancelling`: Cancellation in progress (for long-running jobs).
- `cancelled`: Job was successfully cancelled.

Please refer to the **OpenAPI examples** section on this page for sample job creation requests.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_type":{"description":"The type of job to run. For example, `code_generate` to generate codes or `code_export` to export codes.","type":"string","enum":["code_generate","code_export"],"x-enumDescriptions":{"code_generate":"Generates a batch of unique promotion codes with specified parameters such as code length, prefix, and usage limits.","code_export":"Exports all existing promotion codes for the promotion as a downloadable CSV file."}},"name":{"type":"string","description":"Represents the name of the job. The maximum allowed length is 50 characters.","maxLength":50},"parameters":{"type":"object","properties":{"number_of_codes":{"type":"integer","description":"Specifies the number of codes to be generated.","maximum":1000},"max_uses_per_code":{"type":"integer","description":"Specifies the maximum number of usages per code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times."},"consume_unit":{"type":"string","enum":["per_application","per_checkout"],"description":"Specifies whether the promotion code is consumed per application or per checkout. This determines how usage limits are applied when a code is used multiple times.\n","x-enumDescriptions":{"per_application":"The code is consumed per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage.","per_checkout":"The code is consumed once per checkout, regardless of the number of items in the cart or how many times the promotion is applied within that checkout."}},"code_prefix":{"type":"string","description":"Prefix for generated promotion codes (e.g., `SUMMER-`)."},"code_length":{"type":"integer","description":"Code length.","maximum":16,"minimum":8,"default":8}}},"id":{"type":"string","description":"A unique ID generated when a job is created."},"type":{"type":"string","const":"promotion_job"},"rule_promotion_id":{"description":"A unique ID of a promotion.","type":"string"}},"title":"PromotionJob"}}},"examples":{"GenerateBulkPromotionCodes":{"summary":"Create a Job to Generate 100 Bulk Promotion Codes","description":"Create an asynchronous job to generate **100 unique promotion codes** with specific parameters.\n\n- The `job_type` is `\"code_generate\"`, meaning this job will generate new promotion codes.\n- The `parameters` field defines:\n  - `number_of_codes: 100`, meaning **100 unique codes will be generated**.\n  - `max_uses_per_code: 1`, restricting **each code to a single use**.\n  - `consume_unit: per_checkout`, meaning **each code is consumed once per successful checkout**.\n  - `code_prefix: \"summer-\"`, ensuring that **each generated code starts with \"summer-\"**.\n  - `code_length: 8`, specifying that **each code will have 8 characters after the prefix**.\n\n**Job Processing:**\n- The job will run asynchronously, and the status must be checked separately.\n- You can retrieve the job's status and results using the **Get Rule Promotion Jobs** endpoint.\n","value":{"data":{"type":"promotion_job","job_type":"code_generate","name":"Demo bulk code generate","parameters":{"number_of_codes":100,"max_uses_per_code":1,"consume_unit":"per_checkout","code_prefix":"summer-","code_length":8}}}},"ExportPromotionCodes":{"summary":"Create a Rule Promotion Job to Export All Promotion Codes","description":"Create an asynchronous job to export all **existing promotion codes** as a downloadable CSV file.\n\n**Job Processing:**\n- The job runs asynchronously, and its status must be checked separately.\n- Once the job completes, the exported file will be available for download.\n- You can track the job's status using the **Get Rule Promotion Jobs** endpoint.\n","value":{"data":{"type":"promotion_job","job_type":"code_export","name":"Demo export codes"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Promotion job created","content":{"application/json":{"schema":{"type":"object","description":"Promotion job response","properties":{"data":{"allOf":[{"type":"object","properties":{"job_type":{"description":"The type of job to run. For example, `code_generate` to generate codes or `code_export` to export codes.","type":"string","enum":["code_generate","code_export"],"x-enumDescriptions":{"code_generate":"Generates a batch of unique promotion codes with specified parameters such as code length, prefix, and usage limits.","code_export":"Exports all existing promotion codes for the promotion as a downloadable CSV file."}},"name":{"type":"string","description":"Represents the name of the job. The maximum allowed length is 50 characters.","maxLength":50},"parameters":{"type":"object","properties":{"number_of_codes":{"type":"integer","description":"Specifies the number of codes to be generated.","maximum":1000},"max_uses_per_code":{"type":"integer","description":"Specifies the maximum number of usages per code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times."},"consume_unit":{"type":"string","enum":["per_application","per_checkout"],"description":"Specifies whether the promotion code is consumed per application or per checkout. This determines how usage limits are applied when a code is used multiple times.\n","x-enumDescriptions":{"per_application":"The code is consumed per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage.","per_checkout":"The code is consumed once per checkout, regardless of the number of items in the cart or how many times the promotion is applied within that checkout."}},"code_prefix":{"type":"string","description":"Prefix for generated promotion codes (e.g., `SUMMER-`)."},"code_length":{"type":"integer","description":"Code length.","maximum":16,"minimum":8,"default":8}}},"id":{"type":"string","description":"A unique ID generated when a job is created."},"type":{"type":"string","const":"promotion_job"},"rule_promotion_id":{"description":"A unique ID of a promotion.","type":"string"}},"title":"PromotionJob"},{"type":"object","properties":{"status":{"description":"The status of the job.","type":"string","enum":["pending","processing","completed","failed","cancelling","cancelled"],"x-enumDescriptions":{"pending":"Commerce Cloud has received the request but is currently busy processing other requests.","processing":"Commerce Cloud has initiated processing the job.","completed":"The job is successfully completed.","failed":"The job has failed.","cancelling":"The job is currently in the process of being canceled. You need to wait for the cancellation process to complete.","cancelled":"The job request is canceled."}},"error":{"description":"The error encountered during job execution, if applicable.","type":"string"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The creation date of the job.","type":"string","format":"date-time"},"updated_at":{"description":"The last updated date of the job.","type":"string","format":"date-time"}}}}},"result":{"type":"object","description":"Represents the result of a promotion job, including the number of generated and deleted promotion codes.\n\n- `generated`: Total number of successfully generated codes.\n- `deleted`: Number of codes that were deleted during job cancellation, if applicable.\n","properties":{"generated":{"type":"integer","description":"Number of successfully generated promotion codes.","example":1000},"deleted":{"type":["integer","null"],"description":"Number of codes deleted due to job cancellation.","example":50}},"title":"GenerateResult"}}}],"title":"PromotionJobResponse"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","example":"400"},"title":{"type":"string","example":"Too many jobs"},"detail":{"type":"string","example":"Only 1 pending or processing job is allowed per promotion."}}}}}},"examples":{"TooManyJobsError":{"summary":"Error When Attempting to Create a Job While Another Job is Still Processing","description":"This error occurs when a **new job is requested while another job is still pending or processing** for the same promotion.\n","value":{"errors":[{"status":"400","title":"Too many jobs","detail":"Only 1 pending or processing job is allowed per promotion."}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Rule Promotion

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Rule Promotion"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/rule-promotions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a new rule-based promotion, allowing flexible discount strategies based on cart or item conditions. 
Promotions can apply fixed or percentage-based discounts, apply automatically or via codes, and have eligibility rules 
based on product attributes, cart total, SKU conditions, custom attributes, and more.

This endpoint supports a variety of promotion types, such as:
- **Cart-wide discounts**
- **Item-specific discounts**
- **Shipping discounts**
- **Combinations thereof**

:::note

The minimum item discount amount is zero, both for amounts and percentages.

A store can have a maximum of **50 active and future automatic rule promotions**.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"type":{"type":"string","const":"rule_promotion"},"name":{"type":"string","description":"Specifies a name for the promotion."},"description":{"type":"string","description":"Specifies a description for the rule promotion."},"priority":{"type":"integer","description":"Specifies the priority order of a promotion, with larger numbers indicating higher priorities."},"enabled":{"type":"boolean","description":"Specifies whether the promotion is enabled. The options are true or false, and the default setting is false."},"automatic":{"type":"boolean","description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually."},"stackable":{"type":"boolean","description":"Specifies whether this promotion can stack with other promotions."},"override_stacking":{"type":"boolean","description":"Enables a promotion to be stacked with an otherwise non-stackable promotion."},"start":{"type":"string","format":"date-time","description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. If no time is specified, the default start and end time is set to 00:00."},"end":{"type":"string","format":"date-time","description":"Specifies the end date and time of the promotion or the end date of the promotion."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the promotion."},"store_id":{"type":"string","format":"uuid","description":"Store identifier for the promotion."},"created_by":{"type":"string","description":"User or system that created the promotion."},"updated_by":{"type":"string","description":"User or system that last updated the promotion."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was last updated."}},"required":["created_at","updated_at"]}},"required":["timestamps"]}},"title":"RulePromotionBaseAttributes"},{"type":"object","properties":{"rule_set":{"type":"object","description":"Controls the applicability of the promotion as well as the specific benefit or mechanic of the promotion.","properties":{"catalog_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Specifies the [catalogs](https://elasticpath.dev/docs/api/pxm/catalog/catalogs) that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion."},"currencies":{"type":"array","items":{"type":"string"},"description":"Specifies [currencies](https://elasticpath.dev/docs/api/pxm/currencies/currencies) that are applied for the promotion"},"rules":{"type":"object","description":"The scope or applicability of the promotion (i.e., specifies what conditions must be true for a cart to be eligible for the promotion).","oneOf":[{"type":"object","properties":{"strategy":{"type":"string","const":"account_tags","description":"Considers the tags of the account associated with the cart."},"operator":{"type":"string","x-enumDescriptions":{"contains_all":"All tags must be present in the account.","contains_any":"At least one tag must be present in the account.","not_contains_any":"None of the specified tags must be present in the account (eligible if account has none of these tags).","not_contains_all":"All of the specified tags must not be present in the account (eligible if account is missing at least one tag)."},"enum":["contains_all","contains_any","not_contains_any","not_contains_all"],"description":"Specifies how the arguments are evaluated against the account tags."},"args":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","format":"uuid"},"description":"The `id` of an account tag [Account Tag](/docs/api/accounts/list-account-tags)"}},"title":"AccountTags"},{"type":"object","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND operator that requires ALL child conditions to be satisfied for the promotion to apply. Use when multiple criteria must be met simultaneously (e.g., minimum cart total AND specific customer segment)."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}},"description":"Array of child conditions that must ALL be satisfied."}},"title":"And"},{"type":"object","properties":{"strategy":{"type":"string","const":"cart_custom_attribute","description":"Considers custom attributes associated with the entire shopping cart."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart (in the `custom_attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `custom_attributes` on a cart, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}}},"title":"CartCustomAttributes"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"},{"type":"object","properties":{"strategy":{"const":"cart_total","description":"Considers the total value of items in the shopping cart."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Specifies the kind of restriction on the total amount of the cart.","x-enumDescriptions":{"gte":"The total value of the cart must be greater than or equal to the value specified in `args`","gt":"The total value of the cart must be greater than the value specified in `args`","lte":"The total value of the cart must be less or equal to than the value specified in `args`","lt":"The total value of the cart must be less than the value specified in `args`","eq":"The total value of the cart must be equal to the value specified in `args`","range":"The total value of the cart must be between the first and second values specified in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"},{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"}]}},"title":"CartTotal"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Considers the [Product Templates](/docs/api/pxm/products/extending-products-with-templates) associated with cart items."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The value of the product template for the item must match one of the specified values.","nin":"The value of the product template for the item must **NOT** match one of the specified values."},"description":"Specifies how the arguments are evaluated against the item."},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemAttribute"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_category","description":"Considers the item categories (i.e., the [hierarchy or node](/docs/api/pxm/products/hierarchies)) associated with the item. For particular items, the check is against the node of that item, and all parent nodes."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product is in a node or a sub-node that matches one of the supplied values.","nin":"The product is **NOT** in a node or a sub-node that matches one of the supplied values."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"An array of `id` values for [nodes or hierarchies](/docs/api/pxm/products/get-hierarchy-node)"},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemCategory"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Considers cart items matching by either SKU or Product ID. This strategy is preferred over `item_sku` and `item_product_id`, as it is more flexible."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product must match either the supplied `sku` or `ids`.","nin":"The product must **NOT** match either the supplied `sku` or `ids`."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","summary":"List of SKUs to match","maxItems":400,"items":{"type":"string"},"description":"SKU identifiers for specific product variants. Supports both catalog and custom items."},"ids":{"type":"array","summary":"List of Product IDs to match","maxItems":400,"items":{"type":"string","format":"uuid"},"description":"Product UUID identifiers for broader product targeting. Includes all variants of a product."},"additionalProperties":false}}},"children":{"type":"array","description":"Optional nested rules to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifier"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_price","description":"Considers the price of items in the cart (after discount)"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the price.","x-enumDescriptions":{"gte":"The discounted value of the item must be greater than or equal to the value specified in `args`","gt":"The discounted value of the item must be greater than the value specified in `args`","lte":"The discounted value of the item must be less or equal to than the value specified in `args`","lt":"The discounted value of the item must be less than the value specified in `args`","eq":"The discounted value of the item must be equal to the value specified in `args`"}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number"},"description":"The which we evaluate the rule against."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemPrice"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_product_id","description":"Considers products by matching against their product ID. Can be used for items without a SKU like skuless bundles.\nThe `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The product must match the supplied values.","nin":"The product must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"The `id` of the [products](/docs/api/pxm/products/get-product) to match."}},"title":"ItemProductId"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Considers the quantity of individual items."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the quantity.","x-enumDescriptions":{"gte":"The quantity of the item must be greater than or equal to the value specified in `args`.","gt":"The quantity of the item must be greater than the value specified in `args`.","lte":"The quantity of the item must be less or equal to than the value specified in `args`.","lt":"The quantity of the item must be less than the value specified in `args`.","eq":"The quantity of the item must be equal to the value specified in `args`. When used with `items_bundle`, only this operator is valid."}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","summary":"The value to check against the quantity of the item. (This is the value of `quantity` on a [Cart Item](https://elasticpath.dev/docs/api/carts/get-cart-items))."}}},"title":"ItemQuantity"},{"type":"object","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Matches multiple sets of conditions against distinct cart items."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"},"children":{"type":"array"}}}}},"title":"ItemsBundle"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_sku","description":"Considers products by matching against their SKU.  The `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The sku must match the supplied values.","nin":"The sku must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","minItems":1,"maxItems":400},"description":"The sku of the item to match, can be the sku of a [product](/docs/api/pxm/products/get-product) or a custom item. "}},"title":"ItemSku"},{"type":"object","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR operator that requires ANY child condition to be satisfied for the promotion to apply. Provides flexible eligibility pathways, allowing multiple ways to qualify for a promotion."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}}}},"title":"Or"}]},"actions":{"type":"array","description":"Describes how this promotion should be applied to the cart and order.","items":{"oneOf":[{"type":"object","summary":"Cart Discount","properties":{"strategy":{"type":"string","const":"cart_discount","description":"Applies a discount across the entire cart."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"}]},"condition":{"description":"Specifies which items are eligible for the cart-wide discount. Supports all item-based targeting strategies and logical operations.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"CartDiscount"},{"type":"object","summary":"Item Discount","properties":{"strategy":{"type":"string","const":"item_discount","description":"Applies a discount to particular items in the cart matching the supplied conditions."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","minItems":3,"maxItems":3,"description":"Set the amount to this fixed value.","prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","description":"quantity of eligible units to include in the fixed price assignment","minimum":1},{"type":"integer","description":"total assigned price","minimum":0}],"title":"FixedPriceQuantityArg"}]},"condition":{"description":"Specifies which items are eligible for the discount. Supports logical operations (and/or) and various item targeting strategies.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."},"max_quantity":{"type":"integer","description":"Specifies the maximum quantity of each eligible item to which the promotion is applied."},"items":{"type":"object","properties":{"max_items":{"type":"integer","description":"Specifies the maximum number of items eligible for the discount."},"max_units":{"type":"integer","minimum":1,"description":"Specifies the maximum total quantity of units eligible for the discount across all selected items. Units are sorted by price before selection, defaulting to cheapest first. Use `price_strategy` to change the sort order. For example, with `max_units: 2` and `price_strategy: expensive`, the 2 most expensive units across all eligible items receive the discount, regardless of which SKUs they belong to."},"price_strategy":{"type":"string","x-enumDescriptions":{"cheapest":"The discount is applied to the cheapest item in the cart.","expensive":"The discount is applied to the most expensive item in the cart."},"enum":["cheapest","expensive"],"description":"Specifies the strategy for determining which items to discount based on their individual prices."},"auto_add":{"type":"boolean","description":"This flag determines whether eligible items should be automatically added to the cart. This can only be set to `true` when the target item discount is 100% and the promotion is **automatic**.  Otherwise, the API returns a validation error. NOTE: Item to be auto added should be from PXM catalog."},"show_suggestions":{"type":"boolean","description":"A flag indicating whether to show suggestions for eligible items in the cart if the item is not in the cart."}}}}}},"title":"ItemDiscount"},{"type":"object","summary":"Shipping Discount","properties":{"strategy":{"type":"string","const":"shipping_discount","description":"Applies a discount to the shipping costs on a cart"},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"description":"Specifies which shipping types are eligible for the discount. Only shipping_type strategy is supported for shipping discounts.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"}},"title":"ShippingDiscount"},{"type":"object","summary":"Items Bundle Discount","properties":{"strategy":{"type":"string","const":"items_bundle_discount","description":"Applies a discount to specific combinations of items purchased together."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"type":"object","description":"The condition that gates this action. When present, the action is applied only if the condition is satisfied.\n**Valid top-level strategies:**\n- `cart_total` — gates the action based on the cart total (or filtered item total).\n  Supported on `cart_discount` actions only.\n- `and` / `or` — logical combinators. Children must all be the same level (all\n  cart-level or all item-level). `and`/`or` is only valid at the top level.\n- Item-level strategies (`item_identifier`, `item_price`, `item_quantity`,\n  `item_category`, `item_attribute`, `item_custom_attribute`) — filter which\n  items the cart discount applies to.\n\n**Placement rules for `cart_total`:**\n- Valid at the top level or as a direct child of `and`/`or` (all-cart siblings). - Not valid inside item-level condition children.","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"BundleDiscount"}]}}}}},"title":"RulePromotionBaseRuleSetBaseAttributes"}],"title":"RulePromotionItem"},"examples":{"CartPercentDiscount":{"summary":"Create a Cart Percent Discount Promotion based on cart total value","value":{"data":{"type":"rule_promotion","name":"Cart 20% discount when total is at least $100","description":"20% discount applying to the cart total","enabled":false,"automatic":false,"start":"2024-01-01","end":"2025-01-01","rule_set":{"rules":{"strategy":"cart_total","operator":"gte","args":[10000]},"actions":[{"strategy":"cart_discount","args":["percent",20]}]}}}},"BXGYPromotion":{"summary":"Create a BXGY Promotion. Buy an item and get the other item with discount.","value":{"data":{"type":"rule_promotion","name":"Buy X get Y 50%","description":"Buy item SKU-X Get item SKU-Y 50% off.","enabled":true,"automatic":true,"start":"2024-02-01","end":"2024-02-27","rule_set":{"rules":{"strategy":"item_sku","operator":"in","args":["SKU-X"]},"actions":[{"strategy":"item_discount","args":["percent",50],"condition":[{"strategy":"item_sku","operator":"in","args":["SKU-Y"]}]}]}}}},"ItemPercentWithProductAttribute":{"summary":"Create an Item Percent Discount with Product Attribute","value":{"data":{"type":"rule_promotion","name":"20% off items with attribute brand EP","description":"All items with attribute brand EP get 20% discount.","enabled":true,"automatic":true,"start":"2024-02-01","end":"2050-01-01","rule_set":{"rules":{"strategy":"item_attribute","operator":"in","args":["products(product_template)","brand","string","EP"]},"actions":[{"strategy":"item_discount","args":["percent",20]}]}}}},"MixedCartAndItemDiscount":{"summary":"Create a Mix of Cart and Item Percent Discount Promotions. Applying multiple discounts to the eligible cart.","value":{"data":{"type":"rule_promotion","name":"Buy sku1 and get cart 20% off and item sku1 50%","description":"Buy sku1 get cart 20% off plus item discount 50%.","enabled":true,"automatic":true,"start":"2024-02-01","end":"2024-02-10","rule_set":{"rules":[{"strategy":"item_sku","operator":"in","args":["sku1"]}],"actions":[{"strategy":"item_discount","args":["percent",50],"condition":[{"strategy":"item_sku","operator":"in","args":["sku1"]}]},{"strategy":"cart_discount","args":["percent",20]}]}}}},"FixedItemDiscount":{"summary":"Create an Item Fixed Discount Promotion","value":{"data":{"type":"rule_promotion","name":"Buy item get $10 off","description":"Eligible item gets a fixed discount value of $10.","enabled":true,"automatic":true,"start":"2024-02-10","end":"2024-02-22","rule_set":{"rules":{"strategy":"item_sku","operator":"in","args":["sku1"]},"actions":[{"strategy":"item_discount","args":["fixed",1000]}]}}}},"FixedPriceItemDiscount":{"summary":"Create an Item Fixed Price Discount Promotion. Item price is discounted at a fixed quantity and amount.","value":{"data":{"type":"rule_promotion","name":"Buy 2 items for $100","description":"2 sku1 for $100","enabled":true,"automatic":true,"start":"2024-02-01","end":"2050-01-01","rule_set":{"rules":{"strategy":"item_sku","operator":"in","args":["sku1"]},"actions":[{"strategy":"item_discount","args":["fixed_price",2,10000]}]}}}},"FixedDiscountWithCatalogAndCurrencyConditions":{"summary":"Create a Cart Fixed Discount Promotion for a Specified Catalog and Currencies.","value":{"data":{"type":"rule_promotion","name":"$5 off cart when cart is $100 or more","description":"Cart items from specific catalog with CAD or USD currency can get discount.","enabled":true,"automatic":true,"start":"2023-12-01","end":"2024-01-01","rule_set":{"catalog_ids":["09b9359f-897f-407f-89a2-702e167fe781"],"currencies":["CAD","USD"],"rules":{"strategy":"cart_total","operator":"gte","args":[10000]},"actions":[{"strategy":"cart_discount","args":["fixed",500]}]}}}},"CartCustomAttributePromotion":{"summary":"Create a Cart Percent Discount for any cart with custom attribute can get discount.","value":{"data":{"type":"rule_promotion","name":"50 percent off cart with custom attribute","description":"Cart with specific custom attribute can get discount.","enabled":true,"automatic":true,"start":"2024-01-01","end":"2024-01-26","rule_set":{"rules":{"strategy":"cart_custom_attribute","operator":"in","args":["member_status","string","gold","platinum"]},"actions":[{"strategy":"cart_discount","args":["percent",50]}]}}}},"CartCustomAttributeEqualPromotion":{"summary":"Create a Cart Discount for carts where a custom attribute equals a specific value.","value":{"data":{"type":"rule_promotion","name":"VIP customer discount","description":"15 percent off for VIP customers","enabled":true,"automatic":true,"start":"2025-01-01","end":"2030-12-31","rule_set":{"rules":{"strategy":"cart_custom_attribute","operator":"eq","args":["is_vip","boolean",true]},"actions":[{"strategy":"cart_discount","args":["percent",15]}]}}}},"CartCustomAttributeGreaterThanPromotion":{"summary":"Create a Cart Discount for carts where a custom attribute is greater than a value.","value":{"data":{"type":"rule_promotion","name":"Loyal customer reward","description":"$5 off for customers with more than 5 previous checkouts","enabled":true,"automatic":true,"start":"2025-01-01","end":"2030-12-31","rule_set":{"rules":{"strategy":"cart_custom_attribute","operator":"gt","args":["checkout_count","integer",5]},"actions":[{"strategy":"cart_discount","args":["fixed",500]}]}}}},"CartCustomAttributeLessThanOrEqualPromotion":{"summary":"Create a Cart Discount for carts where a custom attribute is less than or equal to a value.","value":{"data":{"type":"rule_promotion","name":"New customer discount","description":"20 percent off for customers with 3 or fewer checkouts","enabled":true,"automatic":true,"start":"2025-01-01","end":"2030-12-31","rule_set":{"rules":{"strategy":"cart_custom_attribute","operator":"lte","args":["checkout_count","integer",3]},"actions":[{"strategy":"cart_discount","args":["percent",20]}]}}}},"CartCustomAttributeFloatComparisonPromotion":{"summary":"Create a Cart Discount for carts where a float custom attribute exceeds a threshold.","value":{"data":{"type":"rule_promotion","name":"High loyalty score bonus","description":"25 percent off for customers with loyalty score above 75.5","enabled":true,"automatic":true,"start":"2025-01-01","end":"2030-12-31","rule_set":{"rules":{"strategy":"cart_custom_attribute","operator":"gt","args":["loyalty_score","float",75.5]},"actions":[{"strategy":"cart_discount","args":["percent",25]}]}}}},"CartPercentDiscountExcludingItem":{"summary":"Create a Cart Percent Discount Excluding Specific Item.","value":{"data":{"type":"rule_promotion","name":"50 percent off cart excluding excluded item","description":"50 percent off your order excluding excluded item","enabled":true,"automatic":true,"start":"2024-02-01","end":"2050-01-01","rule_set":{"rules":{"strategy":"cart_total","operator":"gte","args":[10000],"children":[{"strategy":"item_sku","operator":"nin","args":["excludedItemSku"]}]},"actions":[{"strategy":"cart_discount","args":["percent",50],"condition":{"strategy":"item_sku","operator":"nin","args":["excludedItemSku"]}}]}}}},"ItemDiscountWithLimitations":{"summary":"Create Item Discount Promotion with Max Quantity Limitation.","value":{"data":{"type":"rule_promotion","name":"Buy a shirt and get max of one hat for free","description":"Buy a shirt and get max of 1 hat free","enabled":true,"automatic":true,"start":"2024-02-01","end":"2050-01-01","rule_set":{"rules":{"strategy":"item_sku","operator":"in","args":["shirt-sku"]},"actions":[{"strategy":"item_discount","args":["percent",100],"limitations":{"max_quantity":1},"condition":[{"strategy":"item_sku","operator":"in","args":["hat-sku"]}]}]}}}},"ItemDiscountWithSkuOrId":{"summary":"Create an Item Percent Discount targeting SKU or Product ID.","value":{"data":{"type":"rule_promotion","name":"Buy an item with SKU or Product ID get item 20% discount","description":"Buy sku1 or item with productID get 20% discount","enabled":true,"automatic":false,"start":"2025-02-01","end":"2050-01-01","rule_set":{"rules":{"strategy":"item_identifier","operator":"in","args":[{"skus":["sku1"],"ids":["44d8077f-8fa3-4780-9df5-91d052be583f"]}]},"actions":[{"strategy":"item_discount","args":["percent",20],"condition":{"strategy":"item_identifier","operator":"in","args":[{"skus":["sku1"],"ids":["44d8077f-8fa3-4780-9df5-91d052be583f"]}]}}]}}}},"ItemDiscountExcludingSkuOrId":{"summary":"Create an item discount excluding SKU or Product ID","value":{"data":{"type":"rule_promotion","name":"Get discount from category excluding sku or id","description":"Promotion excluding items with SKU or Product ID.","enabled":true,"automatic":false,"start":"2025-02-01","end":"2050-01-01","rule_set":{"rules":{"strategy":"item_category","operator":"in","args":["667d9fae-d8c7-4941-b556-70cb4b8612f1"],"children":[{"strategy":"item_identifier","operator":"nin","args":[{"skus":["nike_running1"],"ids":["44d8077f-8fa3-4780-9df5-91d052be583f"]}]}]},"actions":[{"strategy":"item_discount","args":["percent",50],"condition":{"strategy":"item_category","operator":"in","args":["667d9fae-d8c7-4941-b556-70cb4b8612f1"],"children":[{"strategy":"item_identifier","operator":"nin","args":[{"skus":["nike_running1"],"ids":["44d8077f-8fa3-4780-9df5-91d052be583f"]}]}]}}]}}}},"ItemDiscountWithRuleAndActionSubConditions":{"summary":"Create Item Promotion with category and attribute subconditions","value":{"data":{"type":"rule_promotion","name":"Items discount for a category excluding items with sale attribute","description":"50% item discount excluding items with attribute when eligible items exceed $100.","enabled":true,"automatic":true,"start":"2024-02-01","end":"2050-01-01","rule_set":{"rules":{"strategy":"cart_total","operator":"gte","args":[10000],"children":[{"strategy":"item_category","operator":"in","args":["category-id-1"]},{"strategy":"item_attribute","operator":"nin","args":["products(product_template)","sales","string","sale2024"]}]},"actions":[{"strategy":"item_discount","args":["percent",50],"condition":{"strategy":"item_category","operator":"in","args":["category-id-1"],"children":[{"strategy":"item_attribute","operator":"nin","args":["products(product_template)","sales","string","sale2024"]}]}}]}}}},"CategoryItemDiscountWithLimitations":{"summary":"Create Item Promotion targeting a category excluding some items from discount","value":{"data":{"type":"rule_promotion","name":"50% max $10 max 2 items 2 quantities from category","description":"Items from category 50% off max $10 off 2 cheapest items with max quantity of 2 excluding one item.","enabled":true,"automatic":true,"start":"2024-02-01","end":"2050-01-01","rule_set":{"rules":{"strategy":"and","children":[{"strategy":"item_category","operator":"in","args":["e3807d4d-010e-494c-8227-9a5cfd8f1177"]},{"strategy":"item_sku","operator":"nin","args":["exclude_item_sku"]}]},"actions":[{"strategy":"item_discount","args":["percent",50],"limitations":{"max_quantity":2,"max_discount":1000,"items":{"max_items":2,"price_strategy":"cheapest"}}}]}}}},"FreeShippingForCartOver100":{"summary":"Create a Free Shipping Promotion","value":{"data":{"type":"rule_promotion","name":"Free FedEx Ground shipping when cart is $100 or more","description":"Free FedEx Ground shipping when cart is $100 or more.","enabled":true,"automatic":false,"start":"2024-08-01","end":"2050-12-31","rule_set":{"rules":{"strategy":"cart_total","operator":"gte","args":[10000]},"actions":[{"strategy":"shipping_discount","args":["percent",100],"condition":{"strategy":"shipping_type","operator":"in","args":["fedex_ground"]}}]}}}},"ItemsBundleDiscount":{"summary":"Create a Bundle Promotion for specific item skus with specific quantity requirement","value":{"data":{"type":"rule_promotion","name":"Buy 2 tennis rackets and 3 tennis balls, get fixed price bundle discount","description":"Bundle items targeting specific item skus and quantity values.","enabled":true,"automatic":false,"start":"2025-02-01","end":"2025-03-31","rule_set":{"rules":{"strategy":"items_bundle","children":[{"strategy":"and","children":[{"strategy":"item_sku","operator":"in","args":["tennis_racket"]},{"strategy":"item_quantity","operator":"eq","args":[2]}]},{"strategy":"and","children":[{"strategy":"item_sku","operator":"in","args":["tennis_balls"]},{"strategy":"item_quantity","operator":"eq","args":[3]}]}]},"actions":[{"strategy":"items_bundle_discount","args":["fixed_price",20000],"condition":{"strategy":"items_bundle","children":[{"strategy":"and","children":[{"strategy":"item_sku","operator":"in","args":["tennis_racket"]},{"strategy":"item_quantity","operator":"eq","args":[2]}]},{"strategy":"and","children":[{"strategy":"item_sku","operator":"in","args":["tennis_balls"]},{"strategy":"item_quantity","operator":"eq","args":[3]}]}]}}]}}}},"ItemsBundleWithSingleCondition":{"summary":"Create a Bundle Promotion with single condition. Bundle items can be selected from a single category with a required minimum quantity. This can be either a single item meeting the quantity requirement or multiple items whose combined quantity satisfies the requirement.","value":{"data":{"type":"rule_promotion","name":"Buy any 2 or more items from shoes category, get 50% off","description":"Buy any 2 shoes get 50% off.","enabled":true,"automatic":false,"start":"2025-05-01","end":"2025-05-31","rule_set":{"rules":{"strategy":"items_bundle","children":[{"strategy":"and","children":[{"strategy":"item_category","operator":"in","args":["667d9fae-d8c7-4941-b556-70cb4b8612f1"]},{"strategy":"item_quantity","operator":"eq","args":[2]}]}]},"actions":[{"strategy":"items_bundle_discount","args":["percent",50],"condition":{"strategy":"items_bundle","children":[{"strategy":"and","children":[{"strategy":"item_category","operator":"in","args":["667d9fae-d8c7-4941-b556-70cb4b8612f1"]},{"strategy":"item_quantity","operator":"eq","args":[2]}]}]}}]}}}},"BundleWithMixedItemsAcrossCategories":{"summary":"Create a Bundle Promotion with mixed category and item quantity requirements. A bundle promotion that requires items from two categories, allowing the total quantity to be fulfilled by a mix of eligible items.","value":{"data":{"type":"rule_promotion","name":"Buy 2 items each from the \"Shoes\" and \"Socks\" categories to get a 50% bundle discount","description":"Buy 2 items from shoes and socks to get 50% bundle discount.","enabled":true,"automatic":false,"start":"2025-05-01","end":"2025-05-31","rule_set":{"rules":{"strategy":"items_bundle","children":[{"strategy":"and","children":[{"strategy":"item_category","operator":"in","args":["667d9fae-d8c7-4941-b556-70cb4b8612f1"]},{"strategy":"item_quantity","operator":"eq","args":[2]}]},{"strategy":"and","children":[{"strategy":"item_category","operator":"in","args":["7700645a-55bd-4159-a8f3-ade7fed387c4"]},{"strategy":"item_quantity","operator":"eq","args":[2]}]}]},"actions":[{"strategy":"items_bundle_discount","args":["percent",50],"condition":{"strategy":"items_bundle","children":[{"strategy":"and","children":[{"strategy":"item_category","operator":"in","args":["667d9fae-d8c7-4941-b556-70cb4b8612f1"]},{"strategy":"item_quantity","operator":"eq","args":[2]}]},{"strategy":"and","children":[{"strategy":"item_category","operator":"in","args":["7700645a-55bd-4159-a8f3-ade7fed387c4"]},{"strategy":"item_quantity","operator":"eq","args":[2]}]}]}}]}}}},"AccountTagsPromotion":{"summary":"Create a Cart Percent Discount with Account Tags Rule Promotion. Account must contain all account tags to be eligible for the discount.","value":{"data":{"type":"rule_promotion","name":"50 percent off cart with account tags","description":"Account contains all matching account tags get 50 percent cart discount","enabled":true,"automatic":true,"start":"2025-06-01","end":"2026-06-30","rule_set":{"rules":{"strategy":"account_tags","operator":"contains_all","args":["3fa12770-cdf5-4168-a893-9a29eb1b43cc","31d60110-d492-4f93-983a-7cc466f12c54"]},"actions":[{"strategy":"cart_discount","args":["percent",50]}]}}}},"AccountTagsNotContainsAnyPromotion":{"summary":"Create a promotion excluding accounts with any restricted tags. Eligible if account has none of the specified tags.","value":{"data":{"type":"rule_promotion","name":"10 percent off for non-denylisted accounts","description":"Accounts without any of the restricted tags (denylist or fraud) receive a 10% cart discount","enabled":true,"automatic":false,"start":"2025-06-01","end":"2026-06-30","rule_set":{"rules":{"strategy":"account_tags","operator":"not_contains_any","args":["3fa12770-cdf5-4168-a893-9a29eb1b43cc","31d60110-d492-4f93-983a-7cc466f12c54"]},"actions":[{"strategy":"cart_discount","args":["percent",10]}]}}}},"AccountTagsNotContainsAllPromotion":{"summary":"Create a promotion excluding accounts with all restricted tags. Eligible if account is missing at least one of the specified tags.","value":{"data":{"type":"rule_promotion","name":"15 percent off for partially restricted accounts","description":"Accounts that don't have ALL of the specified tags receive a 15% cart discount. Eligible if missing at least one tag.","enabled":true,"automatic":false,"start":"2025-06-01","end":"2026-06-30","rule_set":{"rules":{"strategy":"account_tags","operator":"not_contains_all","args":["3fa12770-cdf5-4168-a893-9a29eb1b43cc","31d60110-d492-4f93-983a-7cc466f12c54"]},"actions":[{"strategy":"cart_discount","args":["percent",15]}]}}}},"AutoAddGiftPromotion":{"summary":"Create an auto add gift promotion. When cart has eligible item,  the discounted item is automatically added to cart.","value":{"data":{"type":"rule_promotion","name":"Buy shoes and get socks for free","description":"Buy shoes and automatically get socks for free","enabled":true,"automatic":true,"start":"2025-06-01","end":"2025-06-30","rule_set":{"rules":{"strategy":"item_identifier","operator":"in","args":[{"skus":["shoes"]}]},"actions":[{"strategy":"item_discount","args":["percent",100],"condition":{"strategy":"item_identifier","operator":"in","args":[{"skus":["socks"]}]},"limitations":{"items":{"auto_add":true}}}]}}}},"CartTotalRangeDiscount":{"summary":"Create a Cart Percent Discount Promotion based on an inclusive cart total range","value":{"data":{"type":"rule_promotion","name":"Cart 20% discount when total is between $100 and $200, inclusive","description":"20% discount applying to carts between $100 and $200, inclusive","enabled":false,"automatic":false,"start":"2024-01-01","end":"2025-01-01","rule_set":{"rules":{"strategy":"cart_total","operator":"range","args":[10000,20000]},"actions":[{"strategy":"cart_discount","args":["percent",20]}]}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","const":"rule_promotion"},"name":{"type":"string","description":"Specifies a name for the promotion."},"description":{"type":"string","description":"Specifies a description for the rule promotion."},"priority":{"type":"integer","description":"Specifies the priority order of a promotion, with larger numbers indicating higher priorities."},"enabled":{"type":"boolean","description":"Specifies whether the promotion is enabled. The options are true or false, and the default setting is false."},"automatic":{"type":"boolean","description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually."},"stackable":{"type":"boolean","description":"Specifies whether this promotion can stack with other promotions."},"override_stacking":{"type":"boolean","description":"Enables a promotion to be stacked with an otherwise non-stackable promotion."},"start":{"type":"string","format":"date-time","description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. If no time is specified, the default start and end time is set to 00:00."},"end":{"type":"string","format":"date-time","description":"Specifies the end date and time of the promotion or the end date of the promotion."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the promotion."},"store_id":{"type":"string","format":"uuid","description":"Store identifier for the promotion."},"created_by":{"type":"string","description":"User or system that created the promotion."},"updated_by":{"type":"string","description":"User or system that last updated the promotion."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was last updated."}},"required":["created_at","updated_at"]}},"required":["timestamps"]}},"title":"RulePromotionBaseAttributes"},{"type":"object","properties":{"rule_set":{"type":"object","description":"Controls the applicability of the promotion as well as the specific benefit or mechanic of the promotion.","properties":{"catalog_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Specifies the [catalogs](https://elasticpath.dev/docs/api/pxm/catalog/catalogs) that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion."},"currencies":{"type":"array","items":{"type":"string"},"description":"Specifies [currencies](https://elasticpath.dev/docs/api/pxm/currencies/currencies) that are applied for the promotion"},"rules":{"type":"object","description":"The scope or applicability of the promotion (i.e., specifies what conditions must be true for a cart to be eligible for the promotion).","oneOf":[{"type":"object","properties":{"strategy":{"type":"string","const":"account_tags","description":"Considers the tags of the account associated with the cart."},"operator":{"type":"string","x-enumDescriptions":{"contains_all":"All tags must be present in the account.","contains_any":"At least one tag must be present in the account.","not_contains_any":"None of the specified tags must be present in the account (eligible if account has none of these tags).","not_contains_all":"All of the specified tags must not be present in the account (eligible if account is missing at least one tag)."},"enum":["contains_all","contains_any","not_contains_any","not_contains_all"],"description":"Specifies how the arguments are evaluated against the account tags."},"args":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","format":"uuid"},"description":"The `id` of an account tag [Account Tag](/docs/api/accounts/list-account-tags)"}},"title":"AccountTags"},{"type":"object","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND operator that requires ALL child conditions to be satisfied for the promotion to apply. Use when multiple criteria must be met simultaneously (e.g., minimum cart total AND specific customer segment)."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}},"description":"Array of child conditions that must ALL be satisfied."}},"title":"And"},{"type":"object","properties":{"strategy":{"type":"string","const":"cart_custom_attribute","description":"Considers custom attributes associated with the entire shopping cart."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart (in the `custom_attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `custom_attributes` on a cart, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}}},"title":"CartCustomAttributes"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"},{"type":"object","properties":{"strategy":{"const":"cart_total","description":"Considers the total value of items in the shopping cart."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Specifies the kind of restriction on the total amount of the cart.","x-enumDescriptions":{"gte":"The total value of the cart must be greater than or equal to the value specified in `args`","gt":"The total value of the cart must be greater than the value specified in `args`","lte":"The total value of the cart must be less or equal to than the value specified in `args`","lt":"The total value of the cart must be less than the value specified in `args`","eq":"The total value of the cart must be equal to the value specified in `args`","range":"The total value of the cart must be between the first and second values specified in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"},{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"}]}},"title":"CartTotal"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Considers the [Product Templates](/docs/api/pxm/products/extending-products-with-templates) associated with cart items."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The value of the product template for the item must match one of the specified values.","nin":"The value of the product template for the item must **NOT** match one of the specified values."},"description":"Specifies how the arguments are evaluated against the item."},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemAttribute"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_category","description":"Considers the item categories (i.e., the [hierarchy or node](/docs/api/pxm/products/hierarchies)) associated with the item. For particular items, the check is against the node of that item, and all parent nodes."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product is in a node or a sub-node that matches one of the supplied values.","nin":"The product is **NOT** in a node or a sub-node that matches one of the supplied values."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"An array of `id` values for [nodes or hierarchies](/docs/api/pxm/products/get-hierarchy-node)"},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemCategory"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Considers cart items matching by either SKU or Product ID. This strategy is preferred over `item_sku` and `item_product_id`, as it is more flexible."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product must match either the supplied `sku` or `ids`.","nin":"The product must **NOT** match either the supplied `sku` or `ids`."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","summary":"List of SKUs to match","maxItems":400,"items":{"type":"string"},"description":"SKU identifiers for specific product variants. Supports both catalog and custom items."},"ids":{"type":"array","summary":"List of Product IDs to match","maxItems":400,"items":{"type":"string","format":"uuid"},"description":"Product UUID identifiers for broader product targeting. Includes all variants of a product."},"additionalProperties":false}}},"children":{"type":"array","description":"Optional nested rules to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifier"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_price","description":"Considers the price of items in the cart (after discount)"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the price.","x-enumDescriptions":{"gte":"The discounted value of the item must be greater than or equal to the value specified in `args`","gt":"The discounted value of the item must be greater than the value specified in `args`","lte":"The discounted value of the item must be less or equal to than the value specified in `args`","lt":"The discounted value of the item must be less than the value specified in `args`","eq":"The discounted value of the item must be equal to the value specified in `args`"}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number"},"description":"The which we evaluate the rule against."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemPrice"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_product_id","description":"Considers products by matching against their product ID. Can be used for items without a SKU like skuless bundles.\nThe `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The product must match the supplied values.","nin":"The product must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"The `id` of the [products](/docs/api/pxm/products/get-product) to match."}},"title":"ItemProductId"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Considers the quantity of individual items."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the quantity.","x-enumDescriptions":{"gte":"The quantity of the item must be greater than or equal to the value specified in `args`.","gt":"The quantity of the item must be greater than the value specified in `args`.","lte":"The quantity of the item must be less or equal to than the value specified in `args`.","lt":"The quantity of the item must be less than the value specified in `args`.","eq":"The quantity of the item must be equal to the value specified in `args`. When used with `items_bundle`, only this operator is valid."}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","summary":"The value to check against the quantity of the item. (This is the value of `quantity` on a [Cart Item](https://elasticpath.dev/docs/api/carts/get-cart-items))."}}},"title":"ItemQuantity"},{"type":"object","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Matches multiple sets of conditions against distinct cart items."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"},"children":{"type":"array"}}}}},"title":"ItemsBundle"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_sku","description":"Considers products by matching against their SKU.  The `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The sku must match the supplied values.","nin":"The sku must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","minItems":1,"maxItems":400},"description":"The sku of the item to match, can be the sku of a [product](/docs/api/pxm/products/get-product) or a custom item. "}},"title":"ItemSku"},{"type":"object","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR operator that requires ANY child condition to be satisfied for the promotion to apply. Provides flexible eligibility pathways, allowing multiple ways to qualify for a promotion."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}}}},"title":"Or"}]},"actions":{"type":"array","description":"Describes how this promotion should be applied to the cart and order.","items":{"oneOf":[{"type":"object","summary":"Cart Discount","properties":{"strategy":{"type":"string","const":"cart_discount","description":"Applies a discount across the entire cart."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"}]},"condition":{"description":"Specifies which items are eligible for the cart-wide discount. Supports all item-based targeting strategies and logical operations.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"CartDiscount"},{"type":"object","summary":"Item Discount","properties":{"strategy":{"type":"string","const":"item_discount","description":"Applies a discount to particular items in the cart matching the supplied conditions."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","minItems":3,"maxItems":3,"description":"Set the amount to this fixed value.","prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","description":"quantity of eligible units to include in the fixed price assignment","minimum":1},{"type":"integer","description":"total assigned price","minimum":0}],"title":"FixedPriceQuantityArg"}]},"condition":{"description":"Specifies which items are eligible for the discount. Supports logical operations (and/or) and various item targeting strategies.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."},"max_quantity":{"type":"integer","description":"Specifies the maximum quantity of each eligible item to which the promotion is applied."},"items":{"type":"object","properties":{"max_items":{"type":"integer","description":"Specifies the maximum number of items eligible for the discount."},"max_units":{"type":"integer","minimum":1,"description":"Specifies the maximum total quantity of units eligible for the discount across all selected items. Units are sorted by price before selection, defaulting to cheapest first. Use `price_strategy` to change the sort order. For example, with `max_units: 2` and `price_strategy: expensive`, the 2 most expensive units across all eligible items receive the discount, regardless of which SKUs they belong to."},"price_strategy":{"type":"string","x-enumDescriptions":{"cheapest":"The discount is applied to the cheapest item in the cart.","expensive":"The discount is applied to the most expensive item in the cart."},"enum":["cheapest","expensive"],"description":"Specifies the strategy for determining which items to discount based on their individual prices."},"auto_add":{"type":"boolean","description":"This flag determines whether eligible items should be automatically added to the cart. This can only be set to `true` when the target item discount is 100% and the promotion is **automatic**.  Otherwise, the API returns a validation error. NOTE: Item to be auto added should be from PXM catalog."},"show_suggestions":{"type":"boolean","description":"A flag indicating whether to show suggestions for eligible items in the cart if the item is not in the cart."}}}}}},"title":"ItemDiscount"},{"type":"object","summary":"Shipping Discount","properties":{"strategy":{"type":"string","const":"shipping_discount","description":"Applies a discount to the shipping costs on a cart"},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"description":"Specifies which shipping types are eligible for the discount. Only shipping_type strategy is supported for shipping discounts.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"}},"title":"ShippingDiscount"},{"type":"object","summary":"Items Bundle Discount","properties":{"strategy":{"type":"string","const":"items_bundle_discount","description":"Applies a discount to specific combinations of items purchased together."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"type":"object","description":"The condition that gates this action. When present, the action is applied only if the condition is satisfied.\n**Valid top-level strategies:**\n- `cart_total` — gates the action based on the cart total (or filtered item total).\n  Supported on `cart_discount` actions only.\n- `and` / `or` — logical combinators. Children must all be the same level (all\n  cart-level or all item-level). `and`/`or` is only valid at the top level.\n- Item-level strategies (`item_identifier`, `item_price`, `item_quantity`,\n  `item_category`, `item_attribute`, `item_custom_attribute`) — filter which\n  items the cart discount applies to.\n\n**Placement rules for `cart_total`:**\n- Valid at the top level or as a direct child of `and`/`or` (all-cart siblings). - Not valid inside item-level condition children.","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"BundleDiscount"}]}}}}},"title":"RulePromotionBaseRuleSetBaseAttributes"}],"title":"RulePromotionItem"}},"title":"RulePromotionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"examples":{"TooManyAutomaticRulePromotions":{"summary":"Error When Attempting to Create an Automatic Rule Promotion While Limit is Reached","description":"This error occurs when attempting to **create an automatic rule promotion while the store has already reached the maximum limit** of 50 active and future automatic rule promotions.\n","value":{"errors":[{"status":"400","title":"Too many automatic rule promotions","detail":"Only 50 active automatic rule promotions are allowed per store"}]}}}}}},"422":{"description":"Duplicate Priority","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"}}}}}}
>
  
</StatusCodes>

---

## Delete Rule Promotion Codes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Rule Promotion Codes"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/rule-promotions/{promotionID}/codes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes one or more promotion codes from a specific rule promotion.

- Supports **bulk deletion**, allowing multiple codes to be removed in a single request.
- Removes promotion codes permanently, making them unavailable for future use.
- If a code has already been redeemed, it will be removed from the system but may still reflect in historical transactions.

A successful request returns a `204 No Content` response, indicating the specified promotion codes have been deleted.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","const":"promotion_codes"},"codes":{"type":"array","description":"Specifies the code details in an array of objects.","items":{"type":"object","properties":{"code":{"type":"string","description":"Specifies the string to use as a code for the promotion."},"uses":{"type":"integer","description":"Specifies the number of times the code can be used. If no value is set, the customer can use the code any number of times."},"user":{"type":"string","description":"Specifies the customer ID of the shopper who can use the code. For more information, see the [Create a customer](/docs/customer-management/customer-management-api/create-a-customer) section."},"consume_unit":{"type":"string","enum":["per_application","per_checkout"],"description":"Specifies whether the code is consumed per application or per checkout. With `per_checkout`, the code is used once for each checkout, regardless of the number of items in the cart. When set to `per_application`, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point.\n"},"max_uses_per_shopper":{"type":"object","description":"Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper.","properties":{"max_uses":{"type":"integer","description":"Sets max number of times the code can be used by a shopper. NOTE - This cannot be set with `per_application` consume unit."},"includes_guests":{"type":"boolean","default":false,"description":"The flag to include guest shoppers for the discount with max use restriction. **If this field is provided, the max_uses value is required.** When set to `true`, guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code. When set to `false`, guest shoppers cannot use the promo code, even if the cart has an associated guest email."}},"title":"MaxUsesPerShopper"},"is_for_new_shopper":{"type":"boolean","description":"A flag indicating whether the coupon is for first-time shoppers. If set to `true`, the discount will only apply if the shopper has never made a payment on any order in the store. If set to `false` or left unset, it will be a regular discount that applies to all shoppers. When this flag is set to `true`, the coupon cannot have usage limitations or be assigned to specific users."}}}}}}},"title":"PromotionCodesRequest"},"examples":{"DeleteCodes":{"summary":"Delete Rule Promotion Codes","value":{"data":{"type":"promotion_codes","codes":[{"code":"spring2024"},{"code":"summer2024","consume_unit":"per_checkout"},{"code":"summer2024_limited","consume_unit":"per_application","uses":5},{"code":"summer2024_memberOnly","consume_unit":"per_application","uses":1,"user":"vip_shopper@email.com"}]}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"}}}}}}
>
  
</StatusCodes>

---

## Delete a Rule Promotion

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Rule Promotion"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/rule-promotions/{promotionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes an existing Rule Promotion identified by its promotion ID.

- This action **permanently removes** the promotion and cannot be undone.
- If the promotion is active, please ensure that its removal does not impact ongoing campaigns.

A successful request returns a `204 No Content` response, indicating that the promotion has been deleted.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the promotion."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"}}}
>
  
</StatusCodes>

---

## Delete A Single Rule Promotion Code

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete A Single Rule Promotion Code"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/rule-promotions/{promotionID}/codes/{codeID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a single promotion code from a specific rule promotion.

- Permanently removes the specified promotion code, making it unavailable for future use.
- Can be used to **revoke a specific code** without affecting other codes under the same promotion.
- If the code has already been redeemed, it will still be removed from the system but may still reflect in historical transactions.

A successful request returns a `204 No Content` response, indicating the specified promotion code has been deleted.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."},{"name":"codeID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion code."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"}}}
>
  
</StatusCodes>

---

## Get a Rule Promotion by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Rule Promotion by ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/rule-promotions/{promotionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a single Rule Promotion by the promotion ID. Responses include promotion specifications such as discount type, eligibility criteria, and configuration details.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","const":"rule_promotion"},"name":{"type":"string","description":"Specifies a name for the promotion."},"description":{"type":"string","description":"Specifies a description for the rule promotion."},"priority":{"type":"integer","description":"Specifies the priority order of a promotion, with larger numbers indicating higher priorities."},"enabled":{"type":"boolean","description":"Specifies whether the promotion is enabled. The options are true or false, and the default setting is false."},"automatic":{"type":"boolean","description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually."},"stackable":{"type":"boolean","description":"Specifies whether this promotion can stack with other promotions."},"override_stacking":{"type":"boolean","description":"Enables a promotion to be stacked with an otherwise non-stackable promotion."},"start":{"type":"string","format":"date-time","description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. If no time is specified, the default start and end time is set to 00:00."},"end":{"type":"string","format":"date-time","description":"Specifies the end date and time of the promotion or the end date of the promotion."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the promotion."},"store_id":{"type":"string","format":"uuid","description":"Store identifier for the promotion."},"created_by":{"type":"string","description":"User or system that created the promotion."},"updated_by":{"type":"string","description":"User or system that last updated the promotion."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was last updated."}},"required":["created_at","updated_at"]}},"required":["timestamps"]}},"title":"RulePromotionBaseAttributes"},{"type":"object","properties":{"rule_set":{"type":"object","description":"Controls the applicability of the promotion as well as the specific benefit or mechanic of the promotion.","properties":{"catalog_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Specifies the [catalogs](https://elasticpath.dev/docs/api/pxm/catalog/catalogs) that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion."},"currencies":{"type":"array","items":{"type":"string"},"description":"Specifies [currencies](https://elasticpath.dev/docs/api/pxm/currencies/currencies) that are applied for the promotion"},"rules":{"type":"object","description":"The scope or applicability of the promotion (i.e., specifies what conditions must be true for a cart to be eligible for the promotion).","oneOf":[{"type":"object","properties":{"strategy":{"type":"string","const":"account_tags","description":"Considers the tags of the account associated with the cart."},"operator":{"type":"string","x-enumDescriptions":{"contains_all":"All tags must be present in the account.","contains_any":"At least one tag must be present in the account.","not_contains_any":"None of the specified tags must be present in the account (eligible if account has none of these tags).","not_contains_all":"All of the specified tags must not be present in the account (eligible if account is missing at least one tag)."},"enum":["contains_all","contains_any","not_contains_any","not_contains_all"],"description":"Specifies how the arguments are evaluated against the account tags."},"args":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","format":"uuid"},"description":"The `id` of an account tag [Account Tag](/docs/api/accounts/list-account-tags)"}},"title":"AccountTags"},{"type":"object","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND operator that requires ALL child conditions to be satisfied for the promotion to apply. Use when multiple criteria must be met simultaneously (e.g., minimum cart total AND specific customer segment)."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}},"description":"Array of child conditions that must ALL be satisfied."}},"title":"And"},{"type":"object","properties":{"strategy":{"type":"string","const":"cart_custom_attribute","description":"Considers custom attributes associated with the entire shopping cart."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart (in the `custom_attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `custom_attributes` on a cart, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}}},"title":"CartCustomAttributes"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"},{"type":"object","properties":{"strategy":{"const":"cart_total","description":"Considers the total value of items in the shopping cart."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Specifies the kind of restriction on the total amount of the cart.","x-enumDescriptions":{"gte":"The total value of the cart must be greater than or equal to the value specified in `args`","gt":"The total value of the cart must be greater than the value specified in `args`","lte":"The total value of the cart must be less or equal to than the value specified in `args`","lt":"The total value of the cart must be less than the value specified in `args`","eq":"The total value of the cart must be equal to the value specified in `args`","range":"The total value of the cart must be between the first and second values specified in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"},{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"}]}},"title":"CartTotal"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Considers the [Product Templates](/docs/api/pxm/products/extending-products-with-templates) associated with cart items."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The value of the product template for the item must match one of the specified values.","nin":"The value of the product template for the item must **NOT** match one of the specified values."},"description":"Specifies how the arguments are evaluated against the item."},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemAttribute"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_category","description":"Considers the item categories (i.e., the [hierarchy or node](/docs/api/pxm/products/hierarchies)) associated with the item. For particular items, the check is against the node of that item, and all parent nodes."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product is in a node or a sub-node that matches one of the supplied values.","nin":"The product is **NOT** in a node or a sub-node that matches one of the supplied values."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"An array of `id` values for [nodes or hierarchies](/docs/api/pxm/products/get-hierarchy-node)"},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemCategory"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Considers cart items matching by either SKU or Product ID. This strategy is preferred over `item_sku` and `item_product_id`, as it is more flexible."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product must match either the supplied `sku` or `ids`.","nin":"The product must **NOT** match either the supplied `sku` or `ids`."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","summary":"List of SKUs to match","maxItems":400,"items":{"type":"string"},"description":"SKU identifiers for specific product variants. Supports both catalog and custom items."},"ids":{"type":"array","summary":"List of Product IDs to match","maxItems":400,"items":{"type":"string","format":"uuid"},"description":"Product UUID identifiers for broader product targeting. Includes all variants of a product."},"additionalProperties":false}}},"children":{"type":"array","description":"Optional nested rules to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifier"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_price","description":"Considers the price of items in the cart (after discount)"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the price.","x-enumDescriptions":{"gte":"The discounted value of the item must be greater than or equal to the value specified in `args`","gt":"The discounted value of the item must be greater than the value specified in `args`","lte":"The discounted value of the item must be less or equal to than the value specified in `args`","lt":"The discounted value of the item must be less than the value specified in `args`","eq":"The discounted value of the item must be equal to the value specified in `args`"}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number"},"description":"The which we evaluate the rule against."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemPrice"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_product_id","description":"Considers products by matching against their product ID. Can be used for items without a SKU like skuless bundles.\nThe `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The product must match the supplied values.","nin":"The product must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"The `id` of the [products](/docs/api/pxm/products/get-product) to match."}},"title":"ItemProductId"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Considers the quantity of individual items."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the quantity.","x-enumDescriptions":{"gte":"The quantity of the item must be greater than or equal to the value specified in `args`.","gt":"The quantity of the item must be greater than the value specified in `args`.","lte":"The quantity of the item must be less or equal to than the value specified in `args`.","lt":"The quantity of the item must be less than the value specified in `args`.","eq":"The quantity of the item must be equal to the value specified in `args`. When used with `items_bundle`, only this operator is valid."}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","summary":"The value to check against the quantity of the item. (This is the value of `quantity` on a [Cart Item](https://elasticpath.dev/docs/api/carts/get-cart-items))."}}},"title":"ItemQuantity"},{"type":"object","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Matches multiple sets of conditions against distinct cart items."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"},"children":{"type":"array"}}}}},"title":"ItemsBundle"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_sku","description":"Considers products by matching against their SKU.  The `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The sku must match the supplied values.","nin":"The sku must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","minItems":1,"maxItems":400},"description":"The sku of the item to match, can be the sku of a [product](/docs/api/pxm/products/get-product) or a custom item. "}},"title":"ItemSku"},{"type":"object","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR operator that requires ANY child condition to be satisfied for the promotion to apply. Provides flexible eligibility pathways, allowing multiple ways to qualify for a promotion."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}}}},"title":"Or"}]},"actions":{"type":"array","description":"Describes how this promotion should be applied to the cart and order.","items":{"oneOf":[{"type":"object","summary":"Cart Discount","properties":{"strategy":{"type":"string","const":"cart_discount","description":"Applies a discount across the entire cart."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"}]},"condition":{"description":"Specifies which items are eligible for the cart-wide discount. Supports all item-based targeting strategies and logical operations.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"CartDiscount"},{"type":"object","summary":"Item Discount","properties":{"strategy":{"type":"string","const":"item_discount","description":"Applies a discount to particular items in the cart matching the supplied conditions."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","minItems":3,"maxItems":3,"description":"Set the amount to this fixed value.","prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","description":"quantity of eligible units to include in the fixed price assignment","minimum":1},{"type":"integer","description":"total assigned price","minimum":0}],"title":"FixedPriceQuantityArg"}]},"condition":{"description":"Specifies which items are eligible for the discount. Supports logical operations (and/or) and various item targeting strategies.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."},"max_quantity":{"type":"integer","description":"Specifies the maximum quantity of each eligible item to which the promotion is applied."},"items":{"type":"object","properties":{"max_items":{"type":"integer","description":"Specifies the maximum number of items eligible for the discount."},"max_units":{"type":"integer","minimum":1,"description":"Specifies the maximum total quantity of units eligible for the discount across all selected items. Units are sorted by price before selection, defaulting to cheapest first. Use `price_strategy` to change the sort order. For example, with `max_units: 2` and `price_strategy: expensive`, the 2 most expensive units across all eligible items receive the discount, regardless of which SKUs they belong to."},"price_strategy":{"type":"string","x-enumDescriptions":{"cheapest":"The discount is applied to the cheapest item in the cart.","expensive":"The discount is applied to the most expensive item in the cart."},"enum":["cheapest","expensive"],"description":"Specifies the strategy for determining which items to discount based on their individual prices."},"auto_add":{"type":"boolean","description":"This flag determines whether eligible items should be automatically added to the cart. This can only be set to `true` when the target item discount is 100% and the promotion is **automatic**.  Otherwise, the API returns a validation error. NOTE: Item to be auto added should be from PXM catalog."},"show_suggestions":{"type":"boolean","description":"A flag indicating whether to show suggestions for eligible items in the cart if the item is not in the cart."}}}}}},"title":"ItemDiscount"},{"type":"object","summary":"Shipping Discount","properties":{"strategy":{"type":"string","const":"shipping_discount","description":"Applies a discount to the shipping costs on a cart"},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"description":"Specifies which shipping types are eligible for the discount. Only shipping_type strategy is supported for shipping discounts.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"}},"title":"ShippingDiscount"},{"type":"object","summary":"Items Bundle Discount","properties":{"strategy":{"type":"string","const":"items_bundle_discount","description":"Applies a discount to specific combinations of items purchased together."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"type":"object","description":"The condition that gates this action. When present, the action is applied only if the condition is satisfied.\n**Valid top-level strategies:**\n- `cart_total` — gates the action based on the cart total (or filtered item total).\n  Supported on `cart_discount` actions only.\n- `and` / `or` — logical combinators. Children must all be the same level (all\n  cart-level or all item-level). `and`/`or` is only valid at the top level.\n- Item-level strategies (`item_identifier`, `item_price`, `item_quantity`,\n  `item_category`, `item_attribute`, `item_custom_attribute`) — filter which\n  items the cart discount applies to.\n\n**Placement rules for `cart_total`:**\n- Valid at the top level or as a direct child of `and`/`or` (all-cart siblings). - Not valid inside item-level condition children.","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"BundleDiscount"}]}}}}},"title":"RulePromotionBaseRuleSetBaseAttributes"}],"title":"RulePromotionItem"}},"title":"RulePromotionResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"}}}}}}
>
  
</StatusCodes>

---

## Get Rule Promotion Code Usages

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Rule Promotion Code Usages"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/rule-promotions/{promotionID}/codes/{code}/usages"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of usage records for a specific Rule Promotion code.

- Provides insights into how many times a specific code was used.
- Can be filtered and paginated to refine results.
- Useful for tracking the performance of individual promotion codes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."},{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"The specific promotion code for which to retrieve usage records."},{"name":"filter","in":"query","required":false,"schema":{"type":"string"},"description":"Filter attributes to refine the results. Supported attributes:\n- `id`: Filter by usage ID.\n- `used_on`: Filter by date with operators `gt`, `ge`, `le`, `lt`.\n","example":"gt(used_on,2024-02-01T00:00:00Z)"},{"name":"page[limit]","in":"query","required":false,"schema":{"type":"integer"},"description":"The number of records per page.","example":10},{"name":"page[offset]","in":"query","required":false,"schema":{"type":"integer"},"description":"The number of records to offset the results by.","example":0}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Represents a single rule promotion usage record.","properties":{"id":{"type":"string","description":"The unique identifier of the usage record."},"order_id":{"type":["string","null"],"description":"The associated order ID, if applicable."},"code_id":{"type":"string","description":"The unique identifier of the promotion code."},"code":{"type":"string","description":"The promotion code used."},"times_used":{"type":"integer","description":"The number of times the promotion code has been used."},"used_on":{"type":"string","format":"date-time","description":"The timestamp when the promotion was applied."},"customer_id":{"type":["string","null"],"description":"The customer identifier who used the promotion, if applicable."},"account_id":{"type":["string","null"],"description":"The account identifier associated with the promotion usage, if applicable."},"customer_email":{"type":["string","null"],"description":"The email of the customer who used the promotion, if applicable."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"updated_at":{"type":"string","format":"date-time","description":"The timestamp when the usage record was last updated."}}}}},"updated_by":{"type":"string","description":"Identifier of the user or system that last updated the record."},"anonymized":{"type":"boolean","description":"Indicates whether the usage record has been anonymized."}},"title":"RulePromotionUsage"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"URL for the current page of results"},"first":{"type":"string","format":"uri","description":"URL for the first page of results"},"last":{"type":"string","format":"uri","description":"URL for the last page of results"},"next":{"type":"string","format":"uri","description":"URL for the next page of results"},"prev":{"type":"string","format":"uri","description":"URL for the previous page of results"}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Offset from the first result"},"total":{"type":"integer","description":"Total number of pages"}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results"},"total_method":{"type":"string","description":"Method used to calculate the total (e.g., 'exact')"}}}},"title":"PaginationMeta"}}},"example":{"data":[{"id":"c2f45a8d-6ebf-4b6a-8b1c-d2e7c9e0f45f","order_id":"1a3b5c7d-9e2f-4a5b-8c1d-6e3f9b0d4c5f","code_id":"5d7e9f2b-3c4a-6b8d-1e9f-0a2b3c4d5e6f","code":"holiday50","times_used":2,"used_on":"2024-02-18T10:30:00.000Z","customer_id":"7e6c5d4b-3a2f-1e9d-8b0c-9f4e7d6c3b5a","customer_email":"vipuser@example.com","meta":{"timestamps":{"updated_at":"2024-02-18T10:35:00.000Z"}},"updated_by":"Admin-User-456"}],"links":{"first":"https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=0&page%5Blimit%5D=10","last":"https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=10&page%5Blimit%5D=10","prev":null,"next":"https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=10&page%5Blimit%5D=10"},"meta":{"pagination":{"total":20,"limit":10,"offset":0,"current":1}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"example":{"errors":[{"status":401,"title":"Unauthorized","detail":"Authentication is required to access this resource."}]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"example":{"errors":[{"status":404,"title":"Promotion Code Not Found","detail":"No usages found for the specified promotion code."}]}}}}}}
>
  
</StatusCodes>

---

## Get Rule Promotion Codes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Rule Promotion Codes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/rule-promotions/{promotionID}/codes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the list of promotion codes associated with a specific Rule Promotion.

- Returns all codes generated for the given promotion ID, including details on usage limits and redemption status.
- Supports both automatically generated and manually created promotion codes.
- Can be used to verify whether a promotion code is still valid or has reached its usage limit.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."},{"name":"filter","in":"query","schema":{"type":"string"},"description":"This parameter accepts a filtering expression that uses specific operators and attributes. Promotion codes are case-insensitive.\n\nThe following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](/guides/Getting-Started/filtering#supported-characters).\n\n| Attribute | Type     | Operator    | Example        |\n|:--------- |:---------|:------------|:---------------|\n| `code`    | `string`, `number` |  `eq`, `gt`       |  `eq(code,summer2024)`, `gt(code,2024)` |\n"},{"name":"sort","in":"query","schema":{"type":"string","enum":["code","-code"],"x-enumDescriptions":{"code":"Sort in increasing order of code, case-insensitively.","-code":"Sort in decreasing order of code, case-insensitively."}},"description":"Specifies the order of the codes that will be returned.\n"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"promotion_codes"},"id":{"type":"string","format":"uuid","description":"Unique identifier for the promotion code"},"code":{"type":"string"},"uses":{"type":"integer"},"user":{"type":"string"},"consume_unit":{"type":"string","enum":["per_application","per_checkout"],"description":"Specifies whether the code is consumed per application or per checkout. With `per_checkout`, the code is used once for each checkout, regardless of the number of items in the cart. When set to `per_application`, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point.\n"},"max_uses":{"type":"integer"},"max_uses_per_shopper":{"type":"object","description":"Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper.","properties":{"max_uses":{"type":"integer","description":"Sets max number of times the code can be used by a shopper. NOTE - This cannot be set with `per_application` consume unit."},"includes_guests":{"type":"boolean","default":false,"description":"The flag to include guest shoppers for the discount with max use restriction. **If this field is provided, the max_uses value is required.** When set to `true`, guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code. When set to `false`, guest shoppers cannot use the promo code, even if the cart has an associated guest email."}},"title":"MaxUsesPerShopper"},"is_for_new_shopper":{"type":"boolean"},"created_by":{"type":"string"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"}}}}}},"title":"GetPromotionCodeResponse"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"URL for the current page of results"},"first":{"type":"string","format":"uri","description":"URL for the first page of results"},"last":{"type":"string","format":"uri","description":"URL for the last page of results"},"next":{"type":"string","format":"uri","description":"URL for the next page of results"},"prev":{"type":"string","format":"uri","description":"URL for the previous page of results"}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Offset from the first result"},"total":{"type":"integer","description":"Total number of pages"}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results"},"total_method":{"type":"string","description":"Method used to calculate the total (e.g., 'exact')"}}}},"title":"PaginationMeta"}},"title":"GetPromotionCodesResponse"}}}}}}
>
  
</StatusCodes>

---

## Get Rule Promotion Code Exported File

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Rule Promotion Code Exported File"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/rule-promotions/{uuid}/jobs/{job-uuid}/file"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the exported promotion codes for a rule promotion job in a CSV format.

- The file contains the generated codes along with relevant metadata.
- This endpoint is applicable only for jobs of type `code_export`.
- The job must be in a `completed` state before the file can be retrieved.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."},{"name":"job-uuid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the job associated with the file."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","description":"Successful response","properties":{"href":{"type":"string","description":"URL to download the CSV file."}},"title":"PromotionCodeExportedFileResponse"}}}}}}
>
  
</StatusCodes>

---

## Get Rule Promotion Jobs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Rule Promotion Jobs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/rule-promotions/{uuid}/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of jobs associated with a specific rule promotion. Each job represents an asynchronous operation such as promotion code generation or export.

The response includes details such as:
- **Job type** (`code_generate` or `code_export`)
- **Job status** (`pending`, `processing`, `completed`, `failed`, `cancelling`, or `cancelled`)
- **Parameters used** (such as number of codes generated)
- **Results** (such as number of codes successfully generated or deleted)

### Filtering
You can filter jobs by:
- **Job Type** (`eq(job_type, code_export)`)
- **Status** (`eq(status, complete)`)

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of a rule promotion."},{"name":"filter","in":"query","required":false,"schema":{"type":"string"},"description":"Specifies filter attributes."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","description":"Successful response","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"job_type":{"description":"The type of job to run. For example, `code_generate` to generate codes or `code_export` to export codes.","type":"string","enum":["code_generate","code_export"],"x-enumDescriptions":{"code_generate":"Generates a batch of unique promotion codes with specified parameters such as code length, prefix, and usage limits.","code_export":"Exports all existing promotion codes for the promotion as a downloadable CSV file."}},"name":{"type":"string","description":"Represents the name of the job. The maximum allowed length is 50 characters.","maxLength":50},"parameters":{"type":"object","properties":{"number_of_codes":{"type":"integer","description":"Specifies the number of codes to be generated.","maximum":1000},"max_uses_per_code":{"type":"integer","description":"Specifies the maximum number of usages per code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times."},"consume_unit":{"type":"string","enum":["per_application","per_checkout"],"description":"Specifies whether the promotion code is consumed per application or per checkout. This determines how usage limits are applied when a code is used multiple times.\n","x-enumDescriptions":{"per_application":"The code is consumed per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage.","per_checkout":"The code is consumed once per checkout, regardless of the number of items in the cart or how many times the promotion is applied within that checkout."}},"code_prefix":{"type":"string","description":"Prefix for generated promotion codes (e.g., `SUMMER-`)."},"code_length":{"type":"integer","description":"Code length.","maximum":16,"minimum":8,"default":8}}},"id":{"type":"string","description":"A unique ID generated when a job is created."},"type":{"type":"string","const":"promotion_job"},"rule_promotion_id":{"description":"A unique ID of a promotion.","type":"string"}},"title":"PromotionJob"},{"type":"object","properties":{"status":{"description":"The status of the job.","type":"string","enum":["pending","processing","completed","failed","cancelling","cancelled"],"x-enumDescriptions":{"pending":"Commerce Cloud has received the request but is currently busy processing other requests.","processing":"Commerce Cloud has initiated processing the job.","completed":"The job is successfully completed.","failed":"The job has failed.","cancelling":"The job is currently in the process of being canceled. You need to wait for the cancellation process to complete.","cancelled":"The job request is canceled."}},"error":{"description":"The error encountered during job execution, if applicable.","type":"string"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"The creation date of the job.","type":"string","format":"date-time"},"updated_at":{"description":"The last updated date of the job.","type":"string","format":"date-time"}}}}},"result":{"type":"object","description":"Represents the result of a promotion job, including the number of generated and deleted promotion codes.\n\n- `generated`: Total number of successfully generated codes.\n- `deleted`: Number of codes that were deleted during job cancellation, if applicable.\n","properties":{"generated":{"type":"integer","description":"Number of successfully generated promotion codes.","example":1000},"deleted":{"type":["integer","null"],"description":"Number of codes deleted due to job cancellation.","example":50}},"title":"GenerateResult"}}}],"title":"PromotionJobResponse"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"URL for the current page of results"},"first":{"type":"string","format":"uri","description":"URL for the first page of results"},"last":{"type":"string","format":"uri","description":"URL for the last page of results"},"next":{"type":"string","format":"uri","description":"URL for the next page of results"},"prev":{"type":"string","format":"uri","description":"URL for the previous page of results"}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Offset from the first result"},"total":{"type":"integer","description":"Total number of pages"}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results"},"total_method":{"type":"string","description":"Method used to calculate the total (e.g., 'exact')"}}}},"title":"PaginationMeta"}},"title":"PromotionJobsListResponse"}}}}}}
>
  
</StatusCodes>

---

## Get Rule Promotion Usages

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Rule Promotion Usages"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/rule-promotions/{promotionID}/usages"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of usage records for a specific Rule Promotion.

- Provides details about when and how a promotion was used.
- Can be filtered and paginated to refine results.
- Useful for analyzing promotion effectiveness and customer engagement.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the rule promotion."},{"name":"filter","in":"query","required":false,"schema":{"type":"string"},"description":"Filter attributes to refine the usage records. Supported attributes:\n- `id`: Filter by usage ID.\n- `code`: Filter by promotion code.\n- `used_on`: Filter by usage date with operators `gt`, `ge`, `le`, `lt`.\n","example":"eq(code,cart1off)"},{"name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","description":"The number of records per page.","example":10}},{"name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","description":"The number of records to offset the results by.","example":0}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Represents a single rule promotion usage record.","properties":{"id":{"type":"string","description":"The unique identifier of the usage record."},"order_id":{"type":["string","null"],"description":"The associated order ID, if applicable."},"code_id":{"type":"string","description":"The unique identifier of the promotion code."},"code":{"type":"string","description":"The promotion code used."},"times_used":{"type":"integer","description":"The number of times the promotion code has been used."},"used_on":{"type":"string","format":"date-time","description":"The timestamp when the promotion was applied."},"customer_id":{"type":["string","null"],"description":"The customer identifier who used the promotion, if applicable."},"account_id":{"type":["string","null"],"description":"The account identifier associated with the promotion usage, if applicable."},"customer_email":{"type":["string","null"],"description":"The email of the customer who used the promotion, if applicable."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"updated_at":{"type":"string","format":"date-time","description":"The timestamp when the usage record was last updated."}}}}},"updated_by":{"type":"string","description":"Identifier of the user or system that last updated the record."},"anonymized":{"type":"boolean","description":"Indicates whether the usage record has been anonymized."}},"title":"RulePromotionUsage"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"URL for the current page of results"},"first":{"type":"string","format":"uri","description":"URL for the first page of results"},"last":{"type":"string","format":"uri","description":"URL for the last page of results"},"next":{"type":"string","format":"uri","description":"URL for the next page of results"},"prev":{"type":"string","format":"uri","description":"URL for the previous page of results"}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Offset from the first result"},"total":{"type":"integer","description":"Total number of pages"}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results"},"total_method":{"type":"string","description":"Method used to calculate the total (e.g., 'exact')"}}}},"title":"PaginationMeta"}}},"example":{"data":[{"id":"a9b73e4d-637f-4f1c-9b3e-2de1f8a70351","order_id":"e3d7b9fa-4a90-4e98-bac2-d7a4b4f2f63f","code_id":"8a2c3f47-9d3b-4562-8392-4e5e6cda3d2b","code":"cart10off","times_used":1,"used_on":"2024-02-20T15:42:00.000Z","customer_id":"4f3e8c5d-37e4-43fb-9276-d1b76f0c3a2a","customer_email":"shopper@example.com","meta":{"timestamps":{"updated_at":"2024-02-20T15:45:00.000Z"}},"updated_by":"Admin-User-123"}],"links":{"first":"https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=0&page%5Blimit%5D=10","last":"https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=90&page%5Blimit%5D=10","prev":null,"next":"https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=10&page%5Blimit%5D=10"},"meta":{"pagination":{"total":100,"limit":10,"offset":0,"current":1}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"example":{"errors":[{"status":401,"title":"Unauthorized","detail":"Authentication is required to access this resource."}]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"example":{"errors":[{"status":404,"title":"Promotion Not Found","detail":"No usages found for the specified promotion ID."}]}}}}}}
>
  
</StatusCodes>

---

## Get Rule Promotions

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Rule Promotions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/rule-promotions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of rule-based promotions, including information such as discount type, eligibility criteria, 
and configuration details. This endpoint supports filtering to refine results based on specific promotion attributes.

Use query parameters to filter promotions by:
- **Code** – Retrieve a specific promotion by its code.
- **Promotion name** – Search for promotions by name.
- **Activation status** – Filter by whether a promotion is active or not.
- **Stackability** – Identify promotions that can or cannot be combined with others.
- **Start and end dates** – Retrieve promotions based on their validity periods.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"filter","in":"query","schema":{"type":"string"},"description":"This parameter accepts a filtering expression that uses specific operators and attributes.  \n\n\nThe following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](/guides/Getting-Started/filtering#supported-characters).\n\n| Attribute                 | Type               | Operator                     | Example                                                               |\n|:--------------------------|:-------------------|:-----------------------------|:----------------------------------------------------------------------|\n| `code`                    | `string`, `number` | `eq`                         | `eq(code,summer2024)`                                                 |\n| `name`                    | `string`           | `like`,`ilike`               | `ilike(name,'Summer *')`                                              |\n| `enabled`                 | `boolean`          | `eq`                         | `eq(enabled, true)`                                                   |\n| `stackable`               | `boolean`          | `eq`                         | `eq(stackable, true)`                                                 |\n| `override_stacking`       | `boolean`          | `eq`                         | `eq(override_stacking, true)`                                         |\n| `start`                   | `date`             | `lt`, `le`, `eq`, `gt`, `ge` | `gt(start, 2025-01-01T00:00:00.000Z)`                                 |\n| `end`                     | `date`             | `lt`, `le`, `eq`, `gt`, `ge` | `lt(end, 2025-01-01T00:00:00.000Z)`                                   |\n| `rule_set.rules.strategy` | `string`           | `eq`, `in`                   | `eq(rule_set.rules.strategy,account_tags)`                            |\n| `rule_set.rules.args`     | `string`           | `contains`                   | `contains(rule_set.rules.args, 11111111-1111-4111-1111-111111111111)` |\n| `account_tags`            | `string`           | `contains`                   | `contains(account_tags, 11111111-1111-4111-1111-111111111111)`              |\n\nSome notes about filters:\n1. The `code` filter is case-insensitive. You can search for codes using only `numbers` or codes containing both `string` and `numbers`.\n2. The `rule_set.rules.*` filters do not search child conditions at present        \n3. The `account_tags` filter will essentially search for any rule or child rule that has an `account_tags` strategy and the associated accounts.\n"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"type":{"type":"string","const":"rule_promotion"},"name":{"type":"string","description":"Specifies a name for the promotion."},"description":{"type":"string","description":"Specifies a description for the rule promotion."},"priority":{"type":"integer","description":"Specifies the priority order of a promotion, with larger numbers indicating higher priorities."},"enabled":{"type":"boolean","description":"Specifies whether the promotion is enabled. The options are true or false, and the default setting is false."},"automatic":{"type":"boolean","description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually."},"stackable":{"type":"boolean","description":"Specifies whether this promotion can stack with other promotions."},"override_stacking":{"type":"boolean","description":"Enables a promotion to be stacked with an otherwise non-stackable promotion."},"start":{"type":"string","format":"date-time","description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. If no time is specified, the default start and end time is set to 00:00."},"end":{"type":"string","format":"date-time","description":"Specifies the end date and time of the promotion or the end date of the promotion."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the promotion."},"store_id":{"type":"string","format":"uuid","description":"Store identifier for the promotion."},"created_by":{"type":"string","description":"User or system that created the promotion."},"updated_by":{"type":"string","description":"User or system that last updated the promotion."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was last updated."}},"required":["created_at","updated_at"]}},"required":["timestamps"]}},"title":"RulePromotionBaseAttributes"},{"type":"object","properties":{"rule_set":{"type":"object","description":"Controls the applicability of the promotion as well as the specific benefit or mechanic of the promotion.","properties":{"catalog_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Specifies the [catalogs](https://elasticpath.dev/docs/api/pxm/catalog/catalogs) that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion."},"currencies":{"type":"array","items":{"type":"string"},"description":"Specifies [currencies](https://elasticpath.dev/docs/api/pxm/currencies/currencies) that are applied for the promotion"},"rules":{"type":"object","description":"The scope or applicability of the promotion (i.e., specifies what conditions must be true for a cart to be eligible for the promotion).","oneOf":[{"type":"object","properties":{"strategy":{"type":"string","const":"account_tags","description":"Considers the tags of the account associated with the cart."},"operator":{"type":"string","x-enumDescriptions":{"contains_all":"All tags must be present in the account.","contains_any":"At least one tag must be present in the account.","not_contains_any":"None of the specified tags must be present in the account (eligible if account has none of these tags).","not_contains_all":"All of the specified tags must not be present in the account (eligible if account is missing at least one tag)."},"enum":["contains_all","contains_any","not_contains_any","not_contains_all"],"description":"Specifies how the arguments are evaluated against the account tags."},"args":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","format":"uuid"},"description":"The `id` of an account tag [Account Tag](/docs/api/accounts/list-account-tags)"}},"title":"AccountTags"},{"type":"object","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND operator that requires ALL child conditions to be satisfied for the promotion to apply. Use when multiple criteria must be met simultaneously (e.g., minimum cart total AND specific customer segment)."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}},"description":"Array of child conditions that must ALL be satisfied."}},"title":"And"},{"type":"object","properties":{"strategy":{"type":"string","const":"cart_custom_attribute","description":"Considers custom attributes associated with the entire shopping cart."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart (in the `custom_attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `custom_attributes` on a cart, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}}},"title":"CartCustomAttributes"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"},{"type":"object","properties":{"strategy":{"const":"cart_total","description":"Considers the total value of items in the shopping cart."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Specifies the kind of restriction on the total amount of the cart.","x-enumDescriptions":{"gte":"The total value of the cart must be greater than or equal to the value specified in `args`","gt":"The total value of the cart must be greater than the value specified in `args`","lte":"The total value of the cart must be less or equal to than the value specified in `args`","lt":"The total value of the cart must be less than the value specified in `args`","eq":"The total value of the cart must be equal to the value specified in `args`","range":"The total value of the cart must be between the first and second values specified in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"},{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"}]}},"title":"CartTotal"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Considers the [Product Templates](/docs/api/pxm/products/extending-products-with-templates) associated with cart items."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The value of the product template for the item must match one of the specified values.","nin":"The value of the product template for the item must **NOT** match one of the specified values."},"description":"Specifies how the arguments are evaluated against the item."},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemAttribute"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_category","description":"Considers the item categories (i.e., the [hierarchy or node](/docs/api/pxm/products/hierarchies)) associated with the item. For particular items, the check is against the node of that item, and all parent nodes."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product is in a node or a sub-node that matches one of the supplied values.","nin":"The product is **NOT** in a node or a sub-node that matches one of the supplied values."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"An array of `id` values for [nodes or hierarchies](/docs/api/pxm/products/get-hierarchy-node)"},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemCategory"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Considers cart items matching by either SKU or Product ID. This strategy is preferred over `item_sku` and `item_product_id`, as it is more flexible."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product must match either the supplied `sku` or `ids`.","nin":"The product must **NOT** match either the supplied `sku` or `ids`."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","summary":"List of SKUs to match","maxItems":400,"items":{"type":"string"},"description":"SKU identifiers for specific product variants. Supports both catalog and custom items."},"ids":{"type":"array","summary":"List of Product IDs to match","maxItems":400,"items":{"type":"string","format":"uuid"},"description":"Product UUID identifiers for broader product targeting. Includes all variants of a product."},"additionalProperties":false}}},"children":{"type":"array","description":"Optional nested rules to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifier"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_price","description":"Considers the price of items in the cart (after discount)"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the price.","x-enumDescriptions":{"gte":"The discounted value of the item must be greater than or equal to the value specified in `args`","gt":"The discounted value of the item must be greater than the value specified in `args`","lte":"The discounted value of the item must be less or equal to than the value specified in `args`","lt":"The discounted value of the item must be less than the value specified in `args`","eq":"The discounted value of the item must be equal to the value specified in `args`"}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number"},"description":"The which we evaluate the rule against."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemPrice"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_product_id","description":"Considers products by matching against their product ID. Can be used for items without a SKU like skuless bundles.\nThe `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The product must match the supplied values.","nin":"The product must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"The `id` of the [products](/docs/api/pxm/products/get-product) to match."}},"title":"ItemProductId"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Considers the quantity of individual items."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the quantity.","x-enumDescriptions":{"gte":"The quantity of the item must be greater than or equal to the value specified in `args`.","gt":"The quantity of the item must be greater than the value specified in `args`.","lte":"The quantity of the item must be less or equal to than the value specified in `args`.","lt":"The quantity of the item must be less than the value specified in `args`.","eq":"The quantity of the item must be equal to the value specified in `args`. When used with `items_bundle`, only this operator is valid."}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","summary":"The value to check against the quantity of the item. (This is the value of `quantity` on a [Cart Item](https://elasticpath.dev/docs/api/carts/get-cart-items))."}}},"title":"ItemQuantity"},{"type":"object","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Matches multiple sets of conditions against distinct cart items."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"},"children":{"type":"array"}}}}},"title":"ItemsBundle"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_sku","description":"Considers products by matching against their SKU.  The `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The sku must match the supplied values.","nin":"The sku must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","minItems":1,"maxItems":400},"description":"The sku of the item to match, can be the sku of a [product](/docs/api/pxm/products/get-product) or a custom item. "}},"title":"ItemSku"},{"type":"object","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR operator that requires ANY child condition to be satisfied for the promotion to apply. Provides flexible eligibility pathways, allowing multiple ways to qualify for a promotion."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}}}},"title":"Or"}]},"actions":{"type":"array","description":"Describes how this promotion should be applied to the cart and order.","items":{"oneOf":[{"type":"object","summary":"Cart Discount","properties":{"strategy":{"type":"string","const":"cart_discount","description":"Applies a discount across the entire cart."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"}]},"condition":{"description":"Specifies which items are eligible for the cart-wide discount. Supports all item-based targeting strategies and logical operations.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"CartDiscount"},{"type":"object","summary":"Item Discount","properties":{"strategy":{"type":"string","const":"item_discount","description":"Applies a discount to particular items in the cart matching the supplied conditions."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","minItems":3,"maxItems":3,"description":"Set the amount to this fixed value.","prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","description":"quantity of eligible units to include in the fixed price assignment","minimum":1},{"type":"integer","description":"total assigned price","minimum":0}],"title":"FixedPriceQuantityArg"}]},"condition":{"description":"Specifies which items are eligible for the discount. Supports logical operations (and/or) and various item targeting strategies.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."},"max_quantity":{"type":"integer","description":"Specifies the maximum quantity of each eligible item to which the promotion is applied."},"items":{"type":"object","properties":{"max_items":{"type":"integer","description":"Specifies the maximum number of items eligible for the discount."},"max_units":{"type":"integer","minimum":1,"description":"Specifies the maximum total quantity of units eligible for the discount across all selected items. Units are sorted by price before selection, defaulting to cheapest first. Use `price_strategy` to change the sort order. For example, with `max_units: 2` and `price_strategy: expensive`, the 2 most expensive units across all eligible items receive the discount, regardless of which SKUs they belong to."},"price_strategy":{"type":"string","x-enumDescriptions":{"cheapest":"The discount is applied to the cheapest item in the cart.","expensive":"The discount is applied to the most expensive item in the cart."},"enum":["cheapest","expensive"],"description":"Specifies the strategy for determining which items to discount based on their individual prices."},"auto_add":{"type":"boolean","description":"This flag determines whether eligible items should be automatically added to the cart. This can only be set to `true` when the target item discount is 100% and the promotion is **automatic**.  Otherwise, the API returns a validation error. NOTE: Item to be auto added should be from PXM catalog."},"show_suggestions":{"type":"boolean","description":"A flag indicating whether to show suggestions for eligible items in the cart if the item is not in the cart."}}}}}},"title":"ItemDiscount"},{"type":"object","summary":"Shipping Discount","properties":{"strategy":{"type":"string","const":"shipping_discount","description":"Applies a discount to the shipping costs on a cart"},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"description":"Specifies which shipping types are eligible for the discount. Only shipping_type strategy is supported for shipping discounts.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"}},"title":"ShippingDiscount"},{"type":"object","summary":"Items Bundle Discount","properties":{"strategy":{"type":"string","const":"items_bundle_discount","description":"Applies a discount to specific combinations of items purchased together."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"type":"object","description":"The condition that gates this action. When present, the action is applied only if the condition is satisfied.\n**Valid top-level strategies:**\n- `cart_total` — gates the action based on the cart total (or filtered item total).\n  Supported on `cart_discount` actions only.\n- `and` / `or` — logical combinators. Children must all be the same level (all\n  cart-level or all item-level). `and`/`or` is only valid at the top level.\n- Item-level strategies (`item_identifier`, `item_price`, `item_quantity`,\n  `item_category`, `item_attribute`, `item_custom_attribute`) — filter which\n  items the cart discount applies to.\n\n**Placement rules for `cart_total`:**\n- Valid at the top level or as a direct child of `and`/`or` (all-cart siblings). - Not valid inside item-level condition children.","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"BundleDiscount"}]}}}}},"title":"RulePromotionBaseRuleSetBaseAttributes"}],"title":"RulePromotionItem"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"URL for the current page of results"},"first":{"type":"string","format":"uri","description":"URL for the first page of results"},"last":{"type":"string","format":"uri","description":"URL for the last page of results"},"next":{"type":"string","format":"uri","description":"URL for the next page of results"},"prev":{"type":"string","format":"uri","description":"URL for the previous page of results"}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Number of items per page"},"offset":{"type":"integer","description":"Offset from the first result"},"total":{"type":"integer","description":"Total number of pages"}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of results"},"total_method":{"type":"string","description":"Method used to calculate the total (e.g., 'exact')"}}}},"title":"PaginationMeta"}},"title":"RulePromotionListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"}}}}}}
>
  
</StatusCodes>

---

## Rule Promotions API

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/promotions-builder/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Rule Promotions API"}
>
</Heading>

Rule Promotions provide the flexibility to offer diverse discounts to shoppers. This functionality supports discounts of varying complexities, from code-based customer discounts, to "Buy X Get Y" scenarios, fixed price promotions, and more based on your business needs.

You can create a Rule Promotion using the Rule Promotions API or through the Promotions Builder in Commerce Manager.

To apply Rule Promotions in carts and orders across an entire store, please enable the `use_rule_promotions` configuration in Cart Settings. You can also update a specific cart to use Rule Promotions by updating the cart's specific discount settings. Please see [Update A Cart](/docs/api/carts/update-a-cart) for more details.  

Enabling Rule Promotions enacts Hybrid Mode, allowing simultaneous use of both Promotions Standard and Rule Promotions discounts.

For example, let's say a store provides the following promotions:
- A Promotions Standard discount for 10% off the shopping cart
- A Rule Promotion offering for a 20% discount on the shopping cart

If a cart qualifies for both discounts based on the respective eligibility criteria, the system applies both types of discounts to the shopping cart, starting with Promotions Standard definitions before applying Rule Promotions.  In this case, the application results in a 10% discount from the Promotions Standard definition and a 20% discount from the Rule Promotion.  

### Rule Set
A rule set is the criteria that determine when and how promotions get applied. Rule Sets consist of rule conditions and corresponding actions, which define eligibility and application details, respectively. Rule Sets may also contain targeted catalogs and currencies for further application granularity.

**Example**
Buy an apple, get an orange 50% off.

Here, buying an apple is the rule and the 50% discount on an orange is the action.

#### Rules
Rules describe the conditions necessary for promotion eligibility. 

In our apple-orange example above, the rule indicates the shopper must buy an apple to get the discount on an orange. In other words, the buying of an apple is the condition which determines eligibility for the corresponding discount.

**Condition Architecture:**
All conditions follow a consistent structure with three primary components: - **`strategy`**: Defines the type of condition (e.g., `cart_total`, `item_category`) - **`operator`**: Specifies how the condition is evaluated (e.g., `gte`, `in`, `contains_all`) - **`args`**: Contains the values to evaluate against
Some conditions support additional components for complex scenarios: - **`children`**: Sub-conditions that provide additional specificity - **`condition`**: Used in actions to define item-specific restrictions

**Condition Categories:** - **Cart-level**: Evaluate entire cart properties (total, custom attributes) - **Account-level**: Consider customer account characteristics (tags, segments)   - **Item-level**: Target specific products, categories, or attributes - **Bundle conditions**: Complex multi-item requirements for "Buy X, Get Y" scenarios - **Logical operators**: AND/OR logic for sophisticated eligibility rules

**Key Design Considerations:** - **Performance**: Order conditions from most to least restrictive for optimal evaluation - **Maintainability**: Use `item_identifier` instead of legacy `item_sku`/`item_product_id` strategies - **Complexity**: Limit nesting depth and consider evaluation costs for complex bundle conditions - **Business Logic**: Ensure condition combinations align with promotion goals and margin requirements

#### Actions
Actions describe how discounts apply to eligible carts and orders. These signify the discount type, level, configurations, and any limitations or restrictions when applying.

Actions can also include:
- Action conditions: specify which items should be included or excluded when applying the discounts. These can be based on factors such as item SKUs, product attributes, quantities, or categories.
- Action limitations: impose restrictions  on the number of products eligible for discounts, maximum discount amounts, and/or total applications for discounts.

In the apple-orange example, the action denotes the system applies a 50% discount to an orange, assuming the eligibility rules are met.  For more complex scenarios, the action might say to provide a 50% discount on up to three oranges or might provide a fixed $1 discount on the two most expensive items from the "fruit" category.

:::note

For promotions that include a mix of item and cart rules or actions, we recommend including the specific item conditions in all item strategies to ensure desired discount applications.

For complex promotions in general, we recommend including specific item conditions on all item strategies to ensure the appropriate items receive discounts.  Please see the [Create a Rule Promotion API Request Examples](/docs/api/promotions-builder/create-rule-promotion) for more details on specifying conditions, restrictions, and inclusions.

:::

#### Action Limitations
Action limitations define constraints or rules that govern how a promotion's action is applied.  While actions specify what discount is given (e.g., 10% off the cart), limitations control how much,  to which items, and under what circumstances that action is applied.
Limitations include:
  - **`max_discount`**: Caps the total value of the discount.
  - **`max_quantity`**: Limits the number of discounted units per item.
  - **`items`**: Restricts how many and which items are eligible, and in what order (e.g., max_items, price_strategy).
    - **`max_items`**: Specifies the maximum number of items eligible for the discount.
    - **`price_strategy`**: Determines how eligible items are selected based on price:
      - **Cheapest (default)**: The discount is applied to the cheapest item(s) in the cart.
      - **Expensive**: The discount applies to the most expensive item(s) in the cart.
    Some limitations, like auto_add, influence the application behavior of the action rather than its scope.
    - **`auto_add`**: Automatically adds items to the cart once conditions are met, 
      providing additional configuration for the promotion’s application mode.
    - **`show_suggestions`**: A flag indicating whether to show suggestions for eligible items in the cart 
      if the item is not in the cart.          

In this way, limitations can affect either the scope of the discount or the manner in which it is applied,  providing both technical and user-facing boundaries around a promotion’s behavior.
For example, consider a **50% discount on items from a category**, with the following limitations:
  - **Applies to a maximum of two items (`max_items: 2`)**
  - **Only applies to the two cheapest eligible items (`price_strategy: cheapest`)**
  - **Limits the total discount to $10 (`max_discount: 1000`)**
  - **Ensures a maximum of two units per eligible item receive the discount (`max_quantity: 2`)**

#### Catalogs and Currencies
As part of the Rule Set, you can also specify the catalogs and currencies for a given Rule Promotion. 

With catalogs defined, the promotion only considers items from the identified catalogs and therefore will not consider custom items or items from other catalogs. With no catalogs defined, the promotion considers all items, including custom items.

Specifying a currency for a Rule Promotion restricts it to carts using that currency.  Rule Promotions support multiple currencies when using a percent discount.  If no currencies are defined, the discount applies to carts in any currency.

### Building Blocks

#### Strategies
Strategies describe the types of condition criteria or application actions used to build a promotion.  A given promotion can be comprised of several strategies in its rules and actions.  These might include several instances of similar strategies, different strategies, or some combination thereof.  Think of these as building blocks that can be applied together to provide a functional discount.

- Rule strategies define the types of conditions that need to be met for eligibility. These might include cart total amount, item prices, cart custom attributes, and more.
- Action strategies refer to the type of action execution run when the eligibility criteria are met. For actions, the possible strategies are `cart_discount`, `item_discount`, `item_bundle_discount` and `shipping_discount`. For more information, please see [Promotions Builder API Overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).
#### Operators and Args
Operators determine how to evaluate a given strategy, while `args` define the value threshold to measure against.  For example, please consider the following condition strategy:

```
{
  "strategy": "cart_total",
  "operator": "gte",
  "args": [ 10000 ]
}
```

In this example, the strategy is `cart_total`, telling the system to assess eligibility based on the total cart value.  The operator is a greater-than-or-equal-to (`gte`) evaluation, indicating the candidate value (in this case, cart total) becomes eligible once it reaches or exceeds the threshold.  Finally, the `args` value provides the threshold value to compare against, 10000.  Taken together, then, this strategy looks for cart totals greater than or equal to 10000.

::: note Different strategies support different operators. For more information, please see [Rule Promotions API Overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview). :::
#### Children and Sub-Conditions
For additional promotion granularity, some strategies support additional specifications via `children` and `condition` fields. 
These fields contain strategies, which provide further specifications around their parent strategy evaluations.  
In other words, sub-conditions refer to additional criteria or conditions that must be met for a particular promotion to be applied.

The following strategies support children/sub-conditions:
- `item_price`
- `item_quantity`
- `item_category`
- `item_attribute`
- `and`
- `or`

Notably, when multiple sub-condition siblings exist, they are combined together, such that all sub-conditions must be met to fulfill eligibility.

### Stacking
Promotion stacking and priority are key elements in managing discounts, ensuring promotions are applied as intended. Stacking allows multiple promotions to be applied to a single cart, either targeting the same items or different ones. The `stackable` flag determines whether a promotion can stack with others, defaulting to `true`. If set to `false`, no other promotion can stack on top, and the highest-priority promotion takes precedence. 

Priority settings dictate the order in which promotions are applied, with higher numbers indicating higher priorities. By default, promotions without assigned priorities are applied in reverse order of creation, with newer promotions applied first and calculated against any existing discounted prices.

Hybrid Mode enables the coexistence of Standard Promotions and those configured in the Promotions Builder, with each functioning independently. This means Standard Promotions can stack alongside non-stackable Builder promotions, and their stackability and priority settings remain unaffected by Standard Promotions.

Override stacking, set using the `override_stacking` flag, provides an additional layer of control over how promotions interact.  This flag determines whether the promotion can stack with other promotions that are typically non-stackable and defaults to `false` when not set. When set to `true`, the promotion can stack with promotions configured as non-stackable, unless those non-stackable promotions also override stacking.

### Shipping
Rule Promotions support shipping discounts, identified by the corresponding strategies during promotion creation.  Shipping discounts apply to shipping group base prices and do not impact shipping taxes or configured shipping fees.  Please see [Shipping Groups](/docs/ship-groups/shipping-groups/index) for more information on creating and interacting with shipping groups.

### Items Bundle
You can promote and discount groups of items together using the `items_bundle` rule strategy and the `items_bundle_discount` action strategy. When these strategies are applied, the cart must contain items that meet all specified criteria to qualify for the discount.
- The `items_bundle` rule strategy defines the required group of items for discount eligibility.
- The `items_bundle_discount` action strategy specifies how the discount is applied to the qualifying group.
- The `items_bundle` strategy requires **at least one** requirement that defines which items are eligible. Bundle items can be mixed across categories or attributes to form a valid bundle.
- The `item_quantity` can be used with any of the bundling strategies, including `item_category`, `item_identifier`, `item_attribute`, etc.
  - `item_quantity` only support `eq` operator when configuring `items_bundle` strategy.
  - For instance, targeting a category with `item_quantity` with operator `eq` 2 means any two items from that category can form a bundle. The system will prioritize individual line items with sufficient quantity first before combining quantities of separate line items.
```
{
   "strategy": "items_bundle",
        "children": [
            {
                "strategy": "and",
                "children": [
                    {
                        "strategy": "item_category",
                        "operator": "in",
                        "args": [
                            "667d9fae-d8c7-4941-b556-70cb4b8612f1"
                        ]
                    },
                    {
                        "strategy": "item_quantity",
                        "operator": "gte",
                        "args": [
                            2
                        ]
                    }
                ]
            }
        ]
}
```
- When using `item_quantity` to target specific items or categories, the required quantity can be fulfilled by a combination of eligible items.
  - For example, if the rule is `item_quantity` with operator `eq` 3 for products in the "Office Supplies" category, the discount will apply when the cart includes any of the following combinations:
    - 2 packs of printer paper + 1 box of pens
    - 1 stapler + 2 notepad
    - 1 box of pens + 1 notepad + 1 pack of printer paper
    - 3 identical items, such as 3 boxes of pens

  - **Please Note**: the system considers line items sequentially based on their quantities, using the order of addition to the cart as a fallback tie-breaker. If the first eligible item has sufficient quantity to fulfill the bundle criteria, it will consume the required quantity and complete the evaluation for that criteria. The system does not re-evaluate these processed items to share any remaining quantities with other items. This behaviour may result in differing total discount amounts for two shopping carts with the same items added in a different order if those items have the same quantity values.

Available discount types:
  - `fixed_price` – Sets a fixed total price for the group (e.g., If the fixed price is set at $100, then the group's subtotal is exactly $100)
  - `percent` – Applies a percentage-based discount to the group.
  - `fixed` – Deducts a fixed amount from the group's total price.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: 
  
    URL: [https://elasticpath.com](https://elasticpath.com)
  

  
    License
  
    MIT

---

## Update a Rule Promotion

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Rule Promotion"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/rule-promotions/{promotionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates an existing Rule Promotion specified by its promotion ID. This includes both **semantic and syntactic validation** to ensure correctness. For example, the start date must be earlier than the end date.

Editable fields include:
- `name`
- `description`
- `enabled`
- `start`
- `end`
- `automatic`
- `stackable`
- `override_stacking`
- `rule_set`

:::note

When updating the `automatic` field from `false` to `true`, the store must not exceed the maximum limit of **50 active and future automatic rule promotions**.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"Authorization","in":"header","description":"The Bearer token required to get access to the API.","required":true,"schema":{"type":"string","format":"Bearer"}},{"name":"promotionID","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier of the promotion to be updated."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"type":{"type":"string","const":"rule_promotion"},"name":{"type":"string","description":"Specifies a name for the promotion."},"description":{"type":"string","description":"Specifies a description for the rule promotion."},"priority":{"type":"integer","description":"Specifies the priority order of a promotion, with larger numbers indicating higher priorities."},"enabled":{"type":"boolean","description":"Specifies whether the promotion is enabled. The options are true or false, and the default setting is false."},"automatic":{"type":"boolean","description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually."},"stackable":{"type":"boolean","description":"Specifies whether this promotion can stack with other promotions."},"override_stacking":{"type":"boolean","description":"Enables a promotion to be stacked with an otherwise non-stackable promotion."},"start":{"type":"string","format":"date-time","description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. If no time is specified, the default start and end time is set to 00:00."},"end":{"type":"string","format":"date-time","description":"Specifies the end date and time of the promotion or the end date of the promotion."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the promotion."},"store_id":{"type":"string","format":"uuid","description":"Store identifier for the promotion."},"created_by":{"type":"string","description":"User or system that created the promotion."},"updated_by":{"type":"string","description":"User or system that last updated the promotion."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was last updated."}},"required":["created_at","updated_at"]}},"required":["timestamps"]}},"title":"RulePromotionBaseAttributes"},{"type":"object","properties":{"rule_set":{"type":"object","description":"Controls the applicability of the promotion as well as the specific benefit or mechanic of the promotion.","properties":{"catalog_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Specifies the [catalogs](https://elasticpath.dev/docs/api/pxm/catalog/catalogs) that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion."},"currencies":{"type":"array","items":{"type":"string"},"description":"Specifies [currencies](https://elasticpath.dev/docs/api/pxm/currencies/currencies) that are applied for the promotion"},"rules":{"type":"object","description":"The scope or applicability of the promotion (i.e., specifies what conditions must be true for a cart to be eligible for the promotion).","oneOf":[{"type":"object","properties":{"strategy":{"type":"string","const":"account_tags","description":"Considers the tags of the account associated with the cart."},"operator":{"type":"string","x-enumDescriptions":{"contains_all":"All tags must be present in the account.","contains_any":"At least one tag must be present in the account.","not_contains_any":"None of the specified tags must be present in the account (eligible if account has none of these tags).","not_contains_all":"All of the specified tags must not be present in the account (eligible if account is missing at least one tag)."},"enum":["contains_all","contains_any","not_contains_any","not_contains_all"],"description":"Specifies how the arguments are evaluated against the account tags."},"args":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","format":"uuid"},"description":"The `id` of an account tag [Account Tag](/docs/api/accounts/list-account-tags)"}},"title":"AccountTags"},{"type":"object","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND operator that requires ALL child conditions to be satisfied for the promotion to apply. Use when multiple criteria must be met simultaneously (e.g., minimum cart total AND specific customer segment)."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}},"description":"Array of child conditions that must ALL be satisfied."}},"title":"And"},{"type":"object","properties":{"strategy":{"type":"string","const":"cart_custom_attribute","description":"Considers custom attributes associated with the entire shopping cart."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart (in the `custom_attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `custom_attributes` on a cart, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}}},"title":"CartCustomAttributes"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"},{"type":"object","properties":{"strategy":{"const":"cart_total","description":"Considers the total value of items in the shopping cart."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Specifies the kind of restriction on the total amount of the cart.","x-enumDescriptions":{"gte":"The total value of the cart must be greater than or equal to the value specified in `args`","gt":"The total value of the cart must be greater than the value specified in `args`","lte":"The total value of the cart must be less or equal to than the value specified in `args`","lt":"The total value of the cart must be less than the value specified in `args`","eq":"The total value of the cart must be equal to the value specified in `args`","range":"The total value of the cart must be between the first and second values specified in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"},{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"}]}},"title":"CartTotal"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Considers the [Product Templates](/docs/api/pxm/products/extending-products-with-templates) associated with cart items."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The value of the product template for the item must match one of the specified values.","nin":"The value of the product template for the item must **NOT** match one of the specified values."},"description":"Specifies how the arguments are evaluated against the item."},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemAttribute"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_category","description":"Considers the item categories (i.e., the [hierarchy or node](/docs/api/pxm/products/hierarchies)) associated with the item. For particular items, the check is against the node of that item, and all parent nodes."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product is in a node or a sub-node that matches one of the supplied values.","nin":"The product is **NOT** in a node or a sub-node that matches one of the supplied values."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"An array of `id` values for [nodes or hierarchies](/docs/api/pxm/products/get-hierarchy-node)"},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemCategory"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Considers cart items matching by either SKU or Product ID. This strategy is preferred over `item_sku` and `item_product_id`, as it is more flexible."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product must match either the supplied `sku` or `ids`.","nin":"The product must **NOT** match either the supplied `sku` or `ids`."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","summary":"List of SKUs to match","maxItems":400,"items":{"type":"string"},"description":"SKU identifiers for specific product variants. Supports both catalog and custom items."},"ids":{"type":"array","summary":"List of Product IDs to match","maxItems":400,"items":{"type":"string","format":"uuid"},"description":"Product UUID identifiers for broader product targeting. Includes all variants of a product."},"additionalProperties":false}}},"children":{"type":"array","description":"Optional nested rules to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifier"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_price","description":"Considers the price of items in the cart (after discount)"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the price.","x-enumDescriptions":{"gte":"The discounted value of the item must be greater than or equal to the value specified in `args`","gt":"The discounted value of the item must be greater than the value specified in `args`","lte":"The discounted value of the item must be less or equal to than the value specified in `args`","lt":"The discounted value of the item must be less than the value specified in `args`","eq":"The discounted value of the item must be equal to the value specified in `args`"}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number"},"description":"The which we evaluate the rule against."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemPrice"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_product_id","description":"Considers products by matching against their product ID. Can be used for items without a SKU like skuless bundles.\nThe `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The product must match the supplied values.","nin":"The product must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"The `id` of the [products](/docs/api/pxm/products/get-product) to match."}},"title":"ItemProductId"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Considers the quantity of individual items."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the quantity.","x-enumDescriptions":{"gte":"The quantity of the item must be greater than or equal to the value specified in `args`.","gt":"The quantity of the item must be greater than the value specified in `args`.","lte":"The quantity of the item must be less or equal to than the value specified in `args`.","lt":"The quantity of the item must be less than the value specified in `args`.","eq":"The quantity of the item must be equal to the value specified in `args`. When used with `items_bundle`, only this operator is valid."}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","summary":"The value to check against the quantity of the item. (This is the value of `quantity` on a [Cart Item](https://elasticpath.dev/docs/api/carts/get-cart-items))."}}},"title":"ItemQuantity"},{"type":"object","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Matches multiple sets of conditions against distinct cart items."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"},"children":{"type":"array"}}}}},"title":"ItemsBundle"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_sku","description":"Considers products by matching against their SKU.  The `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The sku must match the supplied values.","nin":"The sku must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","minItems":1,"maxItems":400},"description":"The sku of the item to match, can be the sku of a [product](/docs/api/pxm/products/get-product) or a custom item. "}},"title":"ItemSku"},{"type":"object","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR operator that requires ANY child condition to be satisfied for the promotion to apply. Provides flexible eligibility pathways, allowing multiple ways to qualify for a promotion."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}}}},"title":"Or"}]},"actions":{"type":"array","description":"Describes how this promotion should be applied to the cart and order.","items":{"oneOf":[{"type":"object","summary":"Cart Discount","properties":{"strategy":{"type":"string","const":"cart_discount","description":"Applies a discount across the entire cart."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"}]},"condition":{"description":"Specifies which items are eligible for the cart-wide discount. Supports all item-based targeting strategies and logical operations.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"CartDiscount"},{"type":"object","summary":"Item Discount","properties":{"strategy":{"type":"string","const":"item_discount","description":"Applies a discount to particular items in the cart matching the supplied conditions."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","minItems":3,"maxItems":3,"description":"Set the amount to this fixed value.","prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","description":"quantity of eligible units to include in the fixed price assignment","minimum":1},{"type":"integer","description":"total assigned price","minimum":0}],"title":"FixedPriceQuantityArg"}]},"condition":{"description":"Specifies which items are eligible for the discount. Supports logical operations (and/or) and various item targeting strategies.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."},"max_quantity":{"type":"integer","description":"Specifies the maximum quantity of each eligible item to which the promotion is applied."},"items":{"type":"object","properties":{"max_items":{"type":"integer","description":"Specifies the maximum number of items eligible for the discount."},"max_units":{"type":"integer","minimum":1,"description":"Specifies the maximum total quantity of units eligible for the discount across all selected items. Units are sorted by price before selection, defaulting to cheapest first. Use `price_strategy` to change the sort order. For example, with `max_units: 2` and `price_strategy: expensive`, the 2 most expensive units across all eligible items receive the discount, regardless of which SKUs they belong to."},"price_strategy":{"type":"string","x-enumDescriptions":{"cheapest":"The discount is applied to the cheapest item in the cart.","expensive":"The discount is applied to the most expensive item in the cart."},"enum":["cheapest","expensive"],"description":"Specifies the strategy for determining which items to discount based on their individual prices."},"auto_add":{"type":"boolean","description":"This flag determines whether eligible items should be automatically added to the cart. This can only be set to `true` when the target item discount is 100% and the promotion is **automatic**.  Otherwise, the API returns a validation error. NOTE: Item to be auto added should be from PXM catalog."},"show_suggestions":{"type":"boolean","description":"A flag indicating whether to show suggestions for eligible items in the cart if the item is not in the cart."}}}}}},"title":"ItemDiscount"},{"type":"object","summary":"Shipping Discount","properties":{"strategy":{"type":"string","const":"shipping_discount","description":"Applies a discount to the shipping costs on a cart"},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"description":"Specifies which shipping types are eligible for the discount. Only shipping_type strategy is supported for shipping discounts.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"}},"title":"ShippingDiscount"},{"type":"object","summary":"Items Bundle Discount","properties":{"strategy":{"type":"string","const":"items_bundle_discount","description":"Applies a discount to specific combinations of items purchased together."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"type":"object","description":"The condition that gates this action. When present, the action is applied only if the condition is satisfied.\n**Valid top-level strategies:**\n- `cart_total` — gates the action based on the cart total (or filtered item total).\n  Supported on `cart_discount` actions only.\n- `and` / `or` — logical combinators. Children must all be the same level (all\n  cart-level or all item-level). `and`/`or` is only valid at the top level.\n- Item-level strategies (`item_identifier`, `item_price`, `item_quantity`,\n  `item_category`, `item_attribute`, `item_custom_attribute`) — filter which\n  items the cart discount applies to.\n\n**Placement rules for `cart_total`:**\n- Valid at the top level or as a direct child of `and`/`or` (all-cart siblings). - Not valid inside item-level condition children.","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"BundleDiscount"}]}}}}},"title":"RulePromotionBaseRuleSetBaseAttributes"}],"title":"RulePromotionItem"},"examples":{"UpdateCartPercentDiscount":{"summary":"Update a Cart Percent Discount Rule Promotion","value":{"data":{"type":"rule_promotion","name":"$10 off cart rule - updated","description":"updated cart rule $10 off your order!","enabled":false,"automatic":false,"rule_set":{"rules":[{"strategy":"cart_total","operator":"lt","args":[1000]}],"actions":[{"strategy":"cart_discount","args":["percent",10]}]}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","const":"rule_promotion"},"name":{"type":"string","description":"Specifies a name for the promotion."},"description":{"type":"string","description":"Specifies a description for the rule promotion."},"priority":{"type":"integer","description":"Specifies the priority order of a promotion, with larger numbers indicating higher priorities."},"enabled":{"type":"boolean","description":"Specifies whether the promotion is enabled. The options are true or false, and the default setting is false."},"automatic":{"type":"boolean","description":"Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually."},"stackable":{"type":"boolean","description":"Specifies whether this promotion can stack with other promotions."},"override_stacking":{"type":"boolean","description":"Enables a promotion to be stacked with an otherwise non-stackable promotion."},"start":{"type":"string","format":"date-time","description":"Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. If no time is specified, the default start and end time is set to 00:00."},"end":{"type":"string","format":"date-time","description":"Specifies the end date and time of the promotion or the end date of the promotion."},"id":{"type":"string","format":"uuid","description":"Unique identifier for the promotion."},"store_id":{"type":"string","format":"uuid","description":"Store identifier for the promotion."},"created_by":{"type":"string","description":"User or system that created the promotion."},"updated_by":{"type":"string","description":"User or system that last updated the promotion."},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the promotion was last updated."}},"required":["created_at","updated_at"]}},"required":["timestamps"]}},"title":"RulePromotionBaseAttributes"},{"type":"object","properties":{"rule_set":{"type":"object","description":"Controls the applicability of the promotion as well as the specific benefit or mechanic of the promotion.","properties":{"catalog_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Specifies the [catalogs](https://elasticpath.dev/docs/api/pxm/catalog/catalogs) that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion."},"currencies":{"type":"array","items":{"type":"string"},"description":"Specifies [currencies](https://elasticpath.dev/docs/api/pxm/currencies/currencies) that are applied for the promotion"},"rules":{"type":"object","description":"The scope or applicability of the promotion (i.e., specifies what conditions must be true for a cart to be eligible for the promotion).","oneOf":[{"type":"object","properties":{"strategy":{"type":"string","const":"account_tags","description":"Considers the tags of the account associated with the cart."},"operator":{"type":"string","x-enumDescriptions":{"contains_all":"All tags must be present in the account.","contains_any":"At least one tag must be present in the account.","not_contains_any":"None of the specified tags must be present in the account (eligible if account has none of these tags).","not_contains_all":"All of the specified tags must not be present in the account (eligible if account is missing at least one tag)."},"enum":["contains_all","contains_any","not_contains_any","not_contains_all"],"description":"Specifies how the arguments are evaluated against the account tags."},"args":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","format":"uuid"},"description":"The `id` of an account tag [Account Tag](/docs/api/accounts/list-account-tags)"}},"title":"AccountTags"},{"type":"object","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND operator that requires ALL child conditions to be satisfied for the promotion to apply. Use when multiple criteria must be met simultaneously (e.g., minimum cart total AND specific customer segment)."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}},"description":"Array of child conditions that must ALL be satisfied."}},"title":"And"},{"type":"object","properties":{"strategy":{"type":"string","const":"cart_custom_attribute","description":"Considers custom attributes associated with the entire shopping cart."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart (in the `custom_attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `custom_attributes` on a cart, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}}},"title":"CartCustomAttributes"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"},{"type":"object","properties":{"strategy":{"const":"cart_total","description":"Considers the total value of items in the shopping cart."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Specifies the kind of restriction on the total amount of the cart.","x-enumDescriptions":{"gte":"The total value of the cart must be greater than or equal to the value specified in `args`","gt":"The total value of the cart must be greater than the value specified in `args`","lte":"The total value of the cart must be less or equal to than the value specified in `args`","lt":"The total value of the cart must be less than the value specified in `args`","eq":"The total value of the cart must be equal to the value specified in `args`","range":"The total value of the cart must be between the first and second values specified in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"},{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"}]}},"title":"CartTotal"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Considers the [Product Templates](/docs/api/pxm/products/extending-products-with-templates) associated with cart items."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The value of the product template for the item must match one of the specified values.","nin":"The value of the product template for the item must **NOT** match one of the specified values."},"description":"Specifies how the arguments are evaluated against the item."},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemAttribute"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_category","description":"Considers the item categories (i.e., the [hierarchy or node](/docs/api/pxm/products/hierarchies)) associated with the item. For particular items, the check is against the node of that item, and all parent nodes."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product is in a node or a sub-node that matches one of the supplied values.","nin":"The product is **NOT** in a node or a sub-node that matches one of the supplied values."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"An array of `id` values for [nodes or hierarchies](/docs/api/pxm/products/get-hierarchy-node)"},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemCategory"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Considers cart items matching by either SKU or Product ID. This strategy is preferred over `item_sku` and `item_product_id`, as it is more flexible."},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The product must match either the supplied `sku` or `ids`.","nin":"The product must **NOT** match either the supplied `sku` or `ids`."},"description":"Specifies the operators used for the rule strategy."},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","summary":"List of SKUs to match","maxItems":400,"items":{"type":"string"},"description":"SKU identifiers for specific product variants. Supports both catalog and custom items."},"ids":{"type":"array","summary":"List of Product IDs to match","maxItems":400,"items":{"type":"string","format":"uuid"},"description":"Product UUID identifiers for broader product targeting. Includes all variants of a product."},"additionalProperties":false}}},"children":{"type":"array","description":"Optional nested rules to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifier"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_price","description":"Considers the price of items in the cart (after discount)"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the price.","x-enumDescriptions":{"gte":"The discounted value of the item must be greater than or equal to the value specified in `args`","gt":"The discounted value of the item must be greater than the value specified in `args`","lte":"The discounted value of the item must be less or equal to than the value specified in `args`","lt":"The discounted value of the item must be less than the value specified in `args`","eq":"The discounted value of the item must be equal to the value specified in `args`"}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number"},"description":"The which we evaluate the rule against."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}}}},"title":"ItemPrice"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_product_id","description":"Considers products by matching against their product ID. Can be used for items without a SKU like skuless bundles.\nThe `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The product must match the supplied values.","nin":"The product must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","format":"uuid","minItems":1,"maxItems":400},"description":"The `id` of the [products](/docs/api/pxm/products/get-product) to match."}},"title":"ItemProductId"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Considers the quantity of individual items."},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq"],"description":"Specifies the kind of restriction on the quantity.","x-enumDescriptions":{"gte":"The quantity of the item must be greater than or equal to the value specified in `args`.","gt":"The quantity of the item must be greater than the value specified in `args`.","lte":"The quantity of the item must be less or equal to than the value specified in `args`.","lt":"The quantity of the item must be less than the value specified in `args`.","eq":"The quantity of the item must be equal to the value specified in `args`. When used with `items_bundle`, only this operator is valid."}},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","summary":"The value to check against the quantity of the item. (This is the value of `quantity` on a [Cart Item](https://elasticpath.dev/docs/api/carts/get-cart-items))."}}},"title":"ItemQuantity"},{"type":"object","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Matches multiple sets of conditions against distinct cart items."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"},"children":{"type":"array"}}}}},"title":"ItemsBundle"},{"type":"object","properties":{"strategy":{"type":"string","const":"item_sku","description":"Considers products by matching against their SKU.  The `item_identifier` strategy is more flexible and recommended instead of this strategy."},"operator":{"type":"string","enum":["in","nin"],"description":"Specifies the operators used for the rule strategy.","x-enumDescriptions":{"in":"The sku must match the supplied values.","nin":"The sku must **NOT** match the supplied values."}},"args":{"type":"array","items":{"type":"string","minItems":1,"maxItems":400},"description":"The sku of the item to match, can be the sku of a [product](/docs/api/pxm/products/get-product) or a custom item. "}},"title":"ItemSku"},{"type":"object","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR operator that requires ANY child condition to be satisfied for the promotion to apply. Provides flexible eligibility pathways, allowing multiple ways to qualify for a promotion."},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","items":{"additionalProperties":true}}}}}},"title":"Or"}]},"actions":{"type":"array","description":"Describes how this promotion should be applied to the cart and order.","items":{"oneOf":[{"type":"object","summary":"Cart Discount","properties":{"strategy":{"type":"string","const":"cart_discount","description":"Applies a discount across the entire cart."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"}]},"condition":{"description":"Specifies which items are eligible for the cart-wide discount. Supports all item-based targeting strategies and logical operations.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"CartDiscount"},{"type":"object","summary":"Item Discount","properties":{"strategy":{"type":"string","const":"item_discount","description":"Applies a discount to particular items in the cart matching the supplied conditions."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","minItems":3,"maxItems":3,"description":"Set the amount to this fixed value.","prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","description":"quantity of eligible units to include in the fixed price assignment","minimum":1},{"type":"integer","description":"total assigned price","minimum":0}],"title":"FixedPriceQuantityArg"}]},"condition":{"description":"Specifies which items are eligible for the discount. Supports logical operations (and/or) and various item targeting strategies.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."},"max_quantity":{"type":"integer","description":"Specifies the maximum quantity of each eligible item to which the promotion is applied."},"items":{"type":"object","properties":{"max_items":{"type":"integer","description":"Specifies the maximum number of items eligible for the discount."},"max_units":{"type":"integer","minimum":1,"description":"Specifies the maximum total quantity of units eligible for the discount across all selected items. Units are sorted by price before selection, defaulting to cheapest first. Use `price_strategy` to change the sort order. For example, with `max_units: 2` and `price_strategy: expensive`, the 2 most expensive units across all eligible items receive the discount, regardless of which SKUs they belong to."},"price_strategy":{"type":"string","x-enumDescriptions":{"cheapest":"The discount is applied to the cheapest item in the cart.","expensive":"The discount is applied to the most expensive item in the cart."},"enum":["cheapest","expensive"],"description":"Specifies the strategy for determining which items to discount based on their individual prices."},"auto_add":{"type":"boolean","description":"This flag determines whether eligible items should be automatically added to the cart. This can only be set to `true` when the target item discount is 100% and the promotion is **automatic**.  Otherwise, the API returns a validation error. NOTE: Item to be auto added should be from PXM catalog."},"show_suggestions":{"type":"boolean","description":"A flag indicating whether to show suggestions for eligible items in the cart if the item is not in the cart."}}}}}},"title":"ItemDiscount"},{"type":"object","summary":"Shipping Discount","properties":{"strategy":{"type":"string","const":"shipping_discount","description":"Applies a discount to the shipping costs on a cart"},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"description":"Specifies which shipping types are eligible for the discount. Only shipping_type strategy is supported for shipping discounts.","type":"object","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"}},"title":"ShippingDiscount"},{"type":"object","summary":"Items Bundle Discount","properties":{"strategy":{"type":"string","const":"items_bundle_discount","description":"Applies a discount to specific combinations of items purchased together."},"args":{"oneOf":[{"type":"array","description":"Apply a fixed discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed"},{"type":"integer","minimum":0}],"title":"FixedArg"},{"type":"array","description":"Apply a percentage based discount to the amount.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"percent"},{"type":"number","minimum":0,"maximum":100}],"title":"PercentArg"},{"type":"array","description":"Set the amount to this fixed value.","minItems":2,"maxItems":2,"prefixItems":[{"type":"string","const":"fixed_price"},{"type":"integer","minimum":0}],"title":"FixedPriceArg"}]},"condition":{"type":"object","description":"The condition that gates this action. When present, the action is applied only if the condition is satisfied.\n**Valid top-level strategies:**\n- `cart_total` — gates the action based on the cart total (or filtered item total).\n  Supported on `cart_discount` actions only.\n- `and` / `or` — logical combinators. Children must all be the same level (all\n  cart-level or all item-level). `and`/`or` is only valid at the top level.\n- Item-level strategies (`item_identifier`, `item_price`, `item_quantity`,\n  `item_category`, `item_attribute`, `item_custom_attribute`) — filter which\n  items the cart discount applies to.\n\n**Placement rules for `cart_total`:**\n- Valid at the top level or as a direct child of `and`/`or` (all-cart siblings). - Not valid inside item-level condition children.","discriminator":{"propertyName":"strategy"},"oneOf":[{"type":"object","description":"Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.\nChildren must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.","properties":{"strategy":{"type":"string","const":"and","description":"Logical AND strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"title":"AndCondition"},{"type":"object","description":"Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.\nThe primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.\nChildren must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.\nFor item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.","properties":{"strategy":{"type":"string","const":"or","description":"Logical OR strategy"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Array of child conditions where ANY one can satisfy the requirement"}},"title":"OrCondition"},{"type":"object","description":"Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.\n**Placement rules:**\n- Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.\n**Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means \"apply this action if the total of matching items is at least $100\". The discount itself still applies to all cart items once the gate passes.","properties":{"strategy":{"type":"string","const":"cart_total","description":"Cart total condition strategy"},"operator":{"type":"string","enum":["gte","gt","lte","lt","eq","range"],"description":"Comparison operator for the cart total threshold.","x-enumDescriptions":{"gte":"Cart total must be greater than or equal to the value in `args`","gt":"Cart total must be greater than the value in `args`","lte":"Cart total must be less than or equal to the value in `args`","lt":"Cart total must be less than the value in `args`","eq":"Cart total must be equal to the value in `args`","range":"Cart total must be between the first and second values in `args` (both inclusive)"}},"args":{"oneOf":[{"type":"array","summary":"The minimum and maximum value of the cart, both are inclusive.","minItems":2,"maxItems":2,"items":{"type":"number"},"title":"CartTotalArg"},{"type":"array","summary":"The total value of the cart.","minItems":1,"maxItems":1,"items":{"type":"number"},"title":"CartTotalRangeArg"}]},"children":{"type":"array","description":"Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"}}},"required":["strategy","operator","args"],"title":"CartTotalCondition"},{"type":"object","description":"Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions.","properties":{"strategy":{"type":"string","const":"item_identifier","description":"Strategy for matching items by SKU or Product ID"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must match (in) or not match (nin) the specified identifiers"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string"},"maxItems":400,"description":"SKUs to match against cart items"},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":400,"description":"Product IDs to match against cart items"}},"additionalProperties":false},"description":"Object containing arrays of identifiers to match"},"children":{"type":"array","description":"Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions.","items":{"type":"object","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Considers custom attributes associated with individual cart items."},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"x-enumDescriptions":{"in":"The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."},"description":"Specifies the restriction on cart item custom_attributes for this rule promotion.\n**Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments"},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute rule. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","description":"The custom attribute key specified on the cart item (in the `attributes` field)."},{"type":"string","description":"The type of the custom attribute on the cart item.","enum":["string","boolean","integer","float"]}],"items":{"description":"The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed.","type":["string","boolean","integer","number"]}},"children":{"type":"array","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array"}}},"description":"Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions."}},"title":"CartItemCustomAttributes"}}},"title":"ItemIdentifierCondition"},{"type":"object","description":"Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators.","properties":{"strategy":{"type":"string","const":"item_price","description":"Strategy for matching items by price"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for price evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Price value for comparison (in minor currency units)"}},"title":"ItemPriceCondition"},{"type":"object","description":"Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds.","properties":{"strategy":{"type":"string","const":"item_quantity","description":"Strategy for matching items by quantity"},"operator":{"type":"string","enum":["gt","gte","lt","lte","eq","ne"],"description":"Comparison operator for quantity evaluation"},"args":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"number","minimum":0},"description":"Quantity value for comparison"}},"title":"ItemQuantityCondition"},{"type":"object","description":"Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path.","properties":{"strategy":{"type":"string","const":"item_category","description":"Strategy for matching items by category"},"operator":{"type":"string","enum":["in","nin"],"x-enumDescriptions":{"in":"The item hierarchy breadcrumbs must include the supplied value.","nin":"The item hierarchy breadcrumbs must **NOT** include the supplied value."},"description":"Whether items must be in (in) or not in (nin) the specified categories"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Category names to match against item breadcrumbs"}},"title":"ItemCategoryCondition"},{"type":"object","description":"Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics.","properties":{"strategy":{"type":"string","const":"item_attribute","description":"Strategy for matching items by attributes"},"operator":{"type":"string","enum":["in","nin"],"description":"Whether items must have (in) or not have (nin) the specified attribute values","x-enumDescriptions":{"in":"The item attributes must include the supplied value","nin":"The item attributes must **NOT** include the supplied value."}},"args":{"type":"array","minItems":4,"maxItems":23,"prefixItems":[{"type":"string","summary":"The product template (e.g., `product(book)`)","minLength":1,"maxLength":255},{"type":"string","summary":"The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template).","minLength":1,"maxLength":255},{"type":"string","summary":"The [`field_type`](/docs/api/flows/fields) of the product template attribute.","enum":["string","boolean","integer","float","date"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`).","type":["string","boolean","integer","number"]}}},"title":"ItemAttributeCondition"},{"type":"object","description":"Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata.","properties":{"strategy":{"type":"string","const":"item_custom_attribute","description":"Strategy for matching cart items by custom attributes"},"operator":{"type":"string","enum":["in","nin","eq","gt","lt","gte","lte"],"description":"Operator for comparing custom attribute values","x-enumDescriptions":{"in":"The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical.","nin":"The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour.","eq":"The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value].","gt":"The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","lt":"The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value].","gte":"The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value].","lte":"The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]."}},"args":{"type":"array","minItems":3,"maxItems":22,"description":"Arguments for the cart item custom attribute condition. The structure depends on the operator:\n- For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments\n**Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible.","prefixItems":[{"type":"string","pattern":"^[A-Za-z0-9_-]{1,255}$","summary":"The custom attribute key specified on the cart item","minLength":1,"maxLength":255},{"type":"string","summary":"The type of the custom attribute value","enum":["string","boolean","integer","float"]}],"items":{"summary":"The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators).","type":["string","boolean","integer","number"]}}},"title":"CartItemCustomAttributeCondition"},{"type":"object","description":"Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions.","properties":{"strategy":{"type":"string","const":"shipping_type","description":"Strategy for matching shipping types"},"operator":{"type":"string","const":"in","description":"Must match one of the specified shipping types"},"args":{"type":"array","minItems":1,"maxItems":400,"items":{"type":"string"},"description":"Shipping type identifiers to match against"}},"title":"ShippingTypeCondition"},{"type":"object","description":"Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups.","properties":{"strategy":{"type":"string","const":"items_bundle","description":"Strategy for matching item bundles"},"children":{"type":"array","items":{"type":"object","description":"Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories.","properties":{"strategy":{"type":"string","description":"The condition strategy type (e.g., item_identifier, item_category, or)"},"operator":{"type":"string","description":"The evaluation operator for the condition"},"args":{"type":"array","items":{"additionalProperties":true},"description":"Arguments/values for the condition evaluation"},"children":{"type":"array","description":"Nested conditions for complex targeting requirements (level 1)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 2)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}},"children":{"type":"array","description":"Nested conditions (level 3)","items":{"type":"object","properties":{"strategy":{"type":"string"},"operator":{"type":"string"},"args":{"type":"array","items":{"additionalProperties":true}}}}}}}}}}}},"title":"BaseCondition"},"description":"Child conditions defining the required items in the bundle"}},"title":"ItemsBundleCondition"}],"title":"Condition"},"limitations":{"type":"object","properties":{"max_discount":{"type":"integer","description":"Specifies the maximum amount of discount applied to the shopping cart."}}}},"title":"BundleDiscount"}]}}}}},"title":"RulePromotionBaseRuleSetBaseAttributes"}],"title":"RulePromotionItem"}},"title":"RulePromotionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"examples":{"TooManyAutomaticRulePromotions":{"summary":"Error When Attempting to Update a Manual Promotion to Automatic While Limit is Reached","description":"This error occurs when attempting to **update a manual rule promotion to automatic while the store has already reached the maximum limit** of 50 active and future automatic rule promotions.\n","value":{"errors":[{"status":"400","title":"Too many automatic rule promotions","detail":"Only 50 active and future automatic rule promotions are allowed per store"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":["string","integer"],"description":"HTTP status code."},"title":{"type":"string","description":"Error title."},"detail":{"type":"string","description":"Error details."},"source":{"type":"string","description":"Source of the error (e.g., which field or parameter caused the error)"},"meta":{"type":"object","properties":{"usage_ids":{"type":"array","items":{"type":"string"}}}}}}}},"title":"Response.Error"},"examples":{"UnprocessableEntity":{"summary":"Unprocessable Entity","value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":""}]}},"DuplicatePriority":{"summary":"Two codes cannot have the same priority","value":{"errors":[{"title":"Duplicate Priority","status":"422","detail":"Priority already in use in another running or scheduled promotion"}]}}}}}}}}
>
  
</StatusCodes>

---

## Administrator Latest Releases Catalog API

Use the Administrator Latest Releases Catalog View API to retrieve product, hierarchy and node information.

:::danger

The Administrator Latest Releases Catalog View API is for Administrator use only. Do not use these endpoints on your customer-facing frontends.

:::

Publishing a catalog creates a release of that catalog that you can use in an organization or in a specific store or other shopper experience. You can retrieve the hierarchies, nodes, and the `live` products associated with a catalog release. You can see which parent nodes a product is associated with. This is useful if want to improve how your shoppers search your store, for example.

Currently, published catalogs are limited to the current release and two releases prior to the current release.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Catalogs Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/catalog/catalog_view.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Catalogs Introduction"}
>
</Heading>

Use the catalog-view Service API to create your catalogs.

You also have the flexibility to create catalogs for different scenarios by combining hierarchies of products with a price book. Scenarios might include:

- Multiple geographical regions. Display different catalogs in different regions with suitable pricing or combine product hierarchies from two different regions to display in a third region.
- Multiple channels. Display different catalogs based on how a shopper accesses your store, such as through a mobile app or a web storefront.
- Direct to business versus direct to customers. Offer different products and prices for business customers versus retail customers.
- Preferred customers. Offer special pricing to preferred customers while displaying a standard price catalog to all other shoppers.
- Reward programs. Enable reward programs where catalog prices drop after a certain spending level is reached.
- Product sales. Offer sale items for a limited time.

Scenarios are created by defining the context within which a catalog is displays. Contexts can be a customer ID, a channel, or any other user-defined tag that can be passed to the APIs from the front-end shopper experiences.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Catalogs

A catalog contains the products available for sale either in your organization or store. A catalog also contains information about how to organize those products for navigation menus and search facets in a shopper experience.

Before you create a catalog you must define the following resources:

- Hierarchies: hierarchies and nodes to categorize the products. See [**Hierarchies**](/docs/api/pxm/products/hierarchies).
- Products: product information, associated assets, and links to hierarchy nodes. See [**Products**](/docs/api/pxm/products/products).
- Price Books: prices for the products associated with the hierarchies. See [**Price Books**](/docs/api/pxm/pricebooks).

A catalog is a combination of hierarchies and a price book.

### Products

Commerce automatically assigns types to the products you create. Product types can be used in catalogs. For example, in your catalog, you can filter on `parent` so that only your parent products are displayed in your storefront.

You can use product tags to store or assign a key word against a product or service that you sell in your store. The product tag can then be used to describe or label that product. Product tags represent similarities between products who do not share the same attributes. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. Product tags can be used in catalogs. For example, you can categorize your products based on color. Your shoppers can then search your products by color, enabling shoppers to quickly find what they are looking for, increasing the likelihood of a purchase, and boosting conversion rates.

### Hierarchies

The hierarchies determine which products appear in the catalog, that is, only the products that are associated with the selected hierarchies are included in the catalog. You can also specify the order you want your hierarchies to display in a published catalog. You can order your hierarchies on a catalog-by-catalog basis.

![Hierarchy_sorting](/assets/hierarchy_sorting.png)

For more information, see [**create a Catalog**](/docs/api/pxm/catalog/create-catalog).

#### Understanding How Products And Nodes Are Associated

You can use `breadcrumb` metadata to understand how products and nodes are associated. it explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within your store.

The `breadcrumb` information that you get in an endpoint response depends on whether the endpoint is retrieving product or node details.

|  Object |  Product/Node |  Description |
| --- | --- | --- |
| `breadcrumb` | Node | A list of nodes that a product is associated with. Up to 10 levels of nodes are displayed, depending on the number of levels of nodes you have. |
| `bread_crumbs` | Product | The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of nodes are displayed, depending on the number of levels of nodes you have. |
| `bread_crumb_nodes` | Product | An array of parent node IDs that a product is associated with. The `bread_crumb_node` metadata lists up to 10 levels of parent nodes, depending on the number of levels of parent nodes you have. |

#### Understanding `bread_crumbs` Metadata

The following diagram illustrates a parent and child nodes.

![Breadcrumbs](/assets/breadcrumbs.PNG)

1. The product is in **Node 2**. The ID for **Node 2** is shown first in the first set of breadcrumbs.
1. **Node 2** is part of **Hierarchy 1**. The ID for **Hierarchy 1** is shown second.
1. **Node 1** is the parent node of **Node 2**. The ID for **Node 1** is shown last.
1. The product is also in **Node 3**. The ID for **Node 3** is shown first in the second set of breadcrumbs.
1. **Node 3** is in the root of **Hierarchy 1**. The ID for **Hierarchy 1** is shown last.

In the `bread_crumb_nodes` metadata, you can see a list of parent nodes a product is associated with.

If you subsequently add a product to a new node, then the `bread_crumb_nodes` metadata appends the new node to the top of the list. Using the example above, if we add the product to **Node 1**:

1. The `bread_crumb_nodes` metadata is generated to show the new node appended to the top of the list.
1. The `bread_crumbs` metadata is updated with the new node.

#### Understanding Breadcrumb Metadata for Child Products

When a catalog is published, the breadcrumb information for a child product includes the metadata mentioned for the parent product, in addition to the information specific to the child product. For example, **Product A** is the parent product, associated with **Node 1** and **Node 2**. The metadata for child **Product B** includes **Node 1** and **Node 2**, in addition to its own metadata information.

### Nodes

The nodes determine which products appear under this in the catalog, that is, only the products that are associated with the selected node are shown under this node.

### Price books

A price book contains the prices for each of the products in the catalog. You can create multiple price books for different scenarios, such as seasonal sales, business versus retail customer pricing, and reward programs. When creating a catalog, you can specify up to five price books. You must set a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. See [Create a catalog](/docs/api/pxm/catalog/create-catalog).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Configure a Shopper Bundle

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Configure a Shopper Bundle"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/catalog/products/{product_id}/configure"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Once you have configured your product bundles, you can display them in your storefront in your published catalog. Depending on how you have configured the minimum and maximum values for the product options in your components, you can allow your shoppers to choose which products they want to select. For example, you can enable a shopper to select 1 or more product options from a list of 10, giving your shoppers greater flexibility when selecting products in your store front.

- Products must be in a `live` status.
- If you have not specified any minimum or maximum values for the product options in your components, your shoppers can select any combination of product options.

If you have configured minimum and maximum values using [Create a Bundle](/docs/api/pxm/products/create-product), this becomes part of the `bundle_configuration`. You can check how your bundle is configured using [Get a product in a catalog release](/docs/api/pxm/catalog/get-product) in `bundle_configuration` under `meta`. The `bundle_configuration` forms the body of the request.

The response updates the `bundle_configuration` with the product options the shopper selects. The `meta` data is updated with the `meta` data of the selected product options. In your storefront, you could display this as a summary of the product options a shopper has selected.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"BundleConfigurationData","description":"Container for a bundle configuration.","properties":{"data":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"}},"required":["data"]}}},"description":"The bundle configuration.","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The configured product of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductData","description":"Container for products.","properties":{"data":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Creates a new catalog

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Creates a new catalog"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/catalogs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Before you create a catalog, you must define the following resources:

- Hierarchies - hierarchies and nodes to categorize the products.
- Products - product information, associated assets, and links to hierarchy nodes.
- Price Books - prices for the products associated with the hierarchies. You can create multiple price books for different scenarios, such as seasonal sales, business versus retail customer pricing, and reward programs. When creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. Priority is a number and the price book with the highest number has the highest priority.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"CatalogCreateData","description":"Creates a catalog with the following attributes.","properties":{"data":{"type":"object","properties":{"attributes":{"type":"object","properties":{"name":{"description":"The name of the catalog.","type":"string","minLength":1,"example":"catalog-123"},"description":{"description":"A brief description of the catalog.","type":"string","example":"Catalog for Store 123","nullable":true},"hierarchy_ids":{"description":"The unique identifiers of the hierarchies to associate with a catalog.","type":"array","items":{"type":"string"}},"pricebook_id":{"description":"The unique identifier of the price book to associate with this catalog. You can specify either a `pricebook_id` or `pricebook_ids` but not both. If you specify both a `pricebook_id` and `pricebook_ids`, a `422 Unprocessable Entity` error is displayed.\n","type":"string"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"string"}}},"enable_price_segmentation":{"description":"This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean","example":true,"default":false,"x-go-name":"EnablePriceSegmentation"},"include_draft_products":{"description":"When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).","type":"boolean","example":false,"default":false,"x-go-name":"IncludeDraftProducts"}},"required":["name","hierarchy_ids"]},"type":{"description":"Represents the type of object being returned. Always `Catalog`.","type":"string","example":"catalog","enum":["catalog"]}},"required":["type","attributes"]}},"required":["data"]}}},"description":"Creates a catalog with the following attributes.","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The created catalog","content":{"application/json":{"schema":{"type":"object","title":"CatalogData","description":"Container for a single catalog.","properties":{"data":{"type":"object","title":"Catalog","description":"Creates a catalog with the following attributes.","properties":{"id":{"type":"string","description":"A unique identifier of a catalog.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog.","type":"string","example":"catalog-123"},"description":{"description":"A brief description of the catalog, such as the purpose of the catalog.","type":"string","example":"Catalog for Store 123","default":""},"hierarchy_ids":{"description":"The unique identifiers of the hierarchies associated with a catalog.","type":"array","items":{"type":"string"}},"pricebook_id":{"description":"The unique identifier of a price book associated with a catalog. If no price book is selected, the catalog is displayed without prices.","type":"string"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"string"}}},"created_at":{"description":"The date and time a catalog is created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog was updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"owner":{"description":"The owner of this resource, can be either `organization` or `store`.","type":"string","enum":["store","organization"],"x-go-name":"Owner","default":"store","nullable":true},"enable_price_segmentation":{"description":"This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean","example":true,"default":false,"x-go-name":"EnablePriceSegmentation"},"include_draft_products":{"description":"When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).","type":"boolean","example":false,"default":false,"x-go-name":"IncludeDraftProducts"}},"required":["name","hierarchy_ids","created_at","updated_at"]},"relationships":{"description":"Relationships are established between different catalog entities. For example, a catalog rule and a price book are related to a catalog, as both are associated with it.","type":"object","title":"CatalogRelationships","properties":{"rules":{"description":"The catalog rules related to a catalog.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"releases":{"description":"When a catalog is published, a catalog release is created. This is a URL to all catalog published releases available for this catalog.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"},"meta":{"type":"object","properties":{"count":{"description":"The number releases available for a catalog.","type":"integer"}}}}}}},"type":{"type":"string","example":"catalog","enum":["catalog"]}},"required":["id","type","attributes"]},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Creates a new catalog rule

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Creates a new catalog rule"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/catalogs/rules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

If you have multiple catalogs, create catalog rule resources. With catalog rules, you can display different catalogs to different shoppers. For example, you can display a preferred pricing catalog to a few special customers. Or you can display one catalog to shoppers using your website and a different catalog to shoppers using your mobile app. Finally, you can define custom criteria by creating tags.

:::note

- If you have one catalog for all customers and channels, you can omit creating this resource.
- Due to the way catalogs are cached in Commerce, using catalog rules to display catalogs sometimes causes a 5-minute time delay before the catalogs are displayed.
- You cannot create catalog rules for organization catalogs.

:::

For ideas about the kinds of business scenarios you can achieve with catalog rules, see [Catalog Rules](/docs/api/pxm/catalog/rules). To understand how catalogs are matched to shoppers by using rules, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"CatalogRuleCreateData","description":"A catalog rule specifies which catalog to use for a given shopper context.","properties":{"data":{"type":"object","properties":{"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog rule. The name must not contain spaces.","type":"string","minLength":1,"example":"rule-123"},"description":{"description":"A brief description of the purpose of a catalog rule.","type":"string","example":"Catalog Rule for most favored customers","default":"","nullable":true},"account_ids":{"description":"The list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.","type":"array","items":{"type":"string"},"nullable":true},"account_tag_ids":{"description":"The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.","type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"description":"The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.","type":"array","items":{"type":"string"},"nullable":true},"channels":{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","type":"array","items":{"type":"string"},"nullable":true},"tags":{"description":"A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","type":"array","items":{"type":"string"},"nullable":true},"schedules":{"description":"Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n","type":"array","items":{"type":"object","title":"Catalog Schedule","description":"A period of time during which a catalog is valid","properties":{"valid_from":{"description":"Matches the date and time that the catalog is displayed from.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"Matches the date and time the catalog is displayed to.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"RuleSchedule"},"nullable":true},"catalog_id":{"type":"string","description":"The unique identifier of a catalog.","example":"d09b4e16-08a5-4f42-817c-6e0d98acbb63"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"}},"required":["name","catalog_id"]},"type":{"description":"This represents the type of object being returned. Always `catalog_rule`.","type":"string","example":"catalog_rule","enum":["catalog_rule"]}},"required":["type","attributes"]}},"required":["data"]}}},"description":"Creates a catalog rule with the following attributes.","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The created catalog rule","content":{"application/json":{"schema":{"type":"object","title":"CatalogRuleData","description":"Container for a single catalog rule.","properties":{"data":{"type":"object","title":"Catalog Rule","description":"A catalog rule specifies which catalog to use for a given shopper context.","properties":{"id":{"type":"string","description":"The catalog rule ID. Use this to get, modify, or delete the catalog rule.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog rule. The name must not contain any spaces.","type":"string","example":"rule-123"},"description":{"description":"A brief description of the purpose of a catalog rule.","type":"string","example":"Catalog Rule for most favored customers","default":"","x-omitempty":true},"account_ids":{"description":"The list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.","type":"array","items":{"type":"string"},"x-omitempty":true},"account_tag_ids":{"description":"The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.","type":"array","items":{"type":"string"},"x-omitempty":true},"customer_ids":{"description":"The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.","type":"array","items":{"type":"string"},"x-omitempty":true},"channels":{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","type":"array","items":{"type":"string"},"x-omitempty":true},"tags":{"description":"A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","type":"array","items":{"type":"string"},"x-omitempty":true},"schedules":{"description":"Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n","type":"array","items":{"type":"object","title":"Catalog Schedule","description":"A period of time during which a catalog is valid","properties":{"valid_from":{"description":"Matches the date and time that the catalog is displayed from.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"Matches the date and time the catalog is displayed to.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"RuleSchedule"},"x-omitempty":true},"catalog_id":{"type":"string","description":"The unique identifier of a catalog.","example":"d09b4e16-08a5-4f42-817c-6e0d98acbb63"},"created_at":{"description":"The date and time a catalog rule was created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog release is updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"}},"required":["name","catalog_id","created_at","updated_at"]},"type":{"description":"This represents the type of object being returned. Always `catalog_rule`.","type":"string","example":"catalog_rule","enum":["catalog_rule"]},"meta":{"type":"object","title":"ruleMeta","description":"A rule's metadata.","properties":{"similarity_score":{"description":"Indicates the similarity score of the rule to the supplied validation request. \nThe score is calculated based on matching criteria:\n- **Name match**: 100 points (exact match)\n- **Account IDs**: 5 points per matching account\n- **Customer IDs**: 5 points per matching customer  \n- **Channels**: 5 points per matching channel\n- **Tags**: 5 points per matching tag\n- **Catalog ID**: 3 points (exact match)\n- **Pricebook IDs**: 2 points per matching pricebook\n- **Schedules**: 2 points per overlapping schedule\n\nHigher scores indicate greater similarity. Rules are sorted by similarity score in descending order.\n","type":"integer","example":100,"x-go-name":"SimilarityScore","x-omitempty":true,"nullable":true},"active":{"description":"will the rule be active at the supplied match date/time?","type":"boolean","example":false,"default":false,"x-go-name":"Active"},"resolved_for_shopper":{"description":"Indicates whether this rule will be the one resolved for a shopper viewing the catalog at the supplied match date/time","type":"boolean","example":true,"default":false},"release_id":{"type":"string","description":"The unique identifier of the published release of the catalog for the rule","x-omitempty":true,"nullable":true}},"x-go-name":"ruleMeta","x-omitempty":true}},"required":["id","type","attributes"]},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Deletes a catalog

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Deletes a catalog"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/catalogs/{catalog_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes an unpublished catalog. Use [**Delete a Release**](/docs/api/pxm/catalog/delete-release-by-id) and [**Delete All Releases**](/docs/api/pxm/catalog/delete-releases) to delete releases of a catalog. If the catalog is associated with any catalog rules, you must first update the catalog rules to remove the catalog.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"A 204 response indicates that the catalog has been deleted."},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Deletes a release

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Deletes a release"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/catalogs/{catalog_id}/releases/{release_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the specified published catalog release.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"A 204 response indicates that the release has been deleted."},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Deletes all releases

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Deletes all releases"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/catalogs/{catalog_id}/releases"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes all releases of the specified published catalog.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"A 204 response indicates that the releases have been deleted."},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Deletes a catalog rule

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Deletes a catalog rule"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/catalogs/rules/{catalog_rule_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a catalog rule

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog rule ID.","name":"catalog_rule_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"A 204 response indicates that the catalog rule has been deleted."},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Hierarchies

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Hierarchies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/hierarchies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the hierarchies from a published catalog.

:::note

Currently, published catalogs are limited to the current release and two releases prior to the current release.

:::

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).

| Operator | Description | Supported Attributes | Example |
|:--- |:--- |:--- |:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug`| `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. | `id` | `filter=in(id,some-id)` | 

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"\nThis endpoints supports filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The hierarchies of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"HierarchyListData","description":"Container for a list of hierarchies.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Hierarchy","description":"A category hierarchy in a catalog. Hierarchies can have parent nodes and child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"HierarchyAttributes","description":"Resource attributes of a catalog hierarchy.","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a hierarchy is published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"description":"A description of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Description"},"name":{"description":"The name of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A unique slug for a hierarchy.","type":"string","example":"formal","x-go-name":"Slug"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a hierarchy was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"HierarchyAttributes"},"id":{"description":"A unique identifier of a hierarchy.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"HierarchyRelationships","description":"Relationships to child nodes, and products.","properties":{"products":{"description":"A URL to all the products associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all the child products associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"nodes":{"description":"A URL to all the nodes associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]}},"x-go-name":"HierarchyRelationships"},"type":{"description":"This represents the type of object being returned. Always `hierarchy`.","type":"string","example":"hierarchy","x-go-name":"Type"},"meta":{"type":"object","title":"HierarchyMeta","description":"A hierarchy's metadata.","properties":{"language":{"description":"Product Experience Manager supports localization of hierarchies. If your store supports multiple languages, you can localize hierarchy names and descriptions. This is [**three-letter language code**](https://www.iso.org/iso-639-language-code) that represents the name of the language you have used.","type":"string","example":"en-GB"},"breadcrumbs":{"description":"Hierarchy Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"HierarchyBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"HierarchyMeta","x-omitempty":true}},"x-go-name":"Hierarchy"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"An unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Nodes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Nodes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the child nodes from a published catalog.

:::note

Currently, published catalogs are limited to the current release and two releases prior to the current release.

:::

You can see the parent nodes a node is associated with in the `breadcrumbs` metadata for each node. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

In a catalog, you can use a filter to return a list of nodes in a hierarchy structure that a product belongs to. You can use this to build breadcrumbs in your storefront. See [Building breadcrumbs in a storefront](#building-breadcrumbs-in-a-storefront).

The response lists the products associated with the nodes. If products are [curated](/guides/How-To/Products/curating-products), they are displayed in `curated_products`. Product curation allows you to promote specific products within each of your hierarchies, enabling you to create unique product collections in your storefront.

- If you don't provide any `curated_products`, products are listed by their `updated_at` time in descending order, with the most recently updated product first.
- If you configure `curated_products` for only a few products, the curated products are displayed first and the other products are displayed in the order of `updated_at` time.
- You can only curate 20 products or less. You cannot have more than 20 curated products.
- If a curated product is removed from a node, the product is also removed from the `curated_products` list.
- A product that is curated has the `"curated_product": true` attribute displayed.

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available.

| Operator  | Description | Attributes | Example |
| --- | --- | --- | --- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug` | `filter=eq(name,some-name)` |
| `in`      | Checks if the values are included in the specified string. If they are, the condition is true.
| `Id` |  `filter=in(id,9214719b-17fe-4ea7-896c-d61e60fc0d05,e104d541-2c52-47fa-8a9a-c4382480d97c,65daaf68-ff2e-4632-8944-370de835967d)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The nodes of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"NodeListData","description":"Container for a list of nodes.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"An unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the products from a published catalog. Only the products in a `live` status are retrieved. Currently, published catalogs are limited to the current release and two releases prior to the current release.

You can see the parent nodes a product is associated with in the `bread_crumbs` and `bread_crumb_nodes` metadata for each product. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

The `variations` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. The `variations` object can then be added to your catalogs. By default, variations and variation options are sorted randomly. You can use the `sort_order` attribute to sort the order of your variation and variation options in `variations`. Once a parent product is published in a catalog, the [Get a List of products in a catalog release](/docs/api/pxm/catalog/get-all-products) response displays the sorted variations and variation options. Variations and variation options are displayed in descending order according to their `sort_order` values.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter           | Required | Description                                                                                                                                                                                                           |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product.                                                                                                           |
| `files`              | Optional | Any files associated with a product. 

See [**Including Resources**](/guides/Getting-Started/includes).

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. For `product_types`, you can only specify one product type. For example, `filter=eq(product_types,child)`.            | `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags` | `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. For `product_types`, you can specify more than one product type. For example, `filter=in(product_types,child,bundle)`. | `id`, `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags`          | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","style":"simple","schema":{"type":"array","items":{"type":"string"},"maxItems":5}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","style":"simple","schema":{"type":"array","items":{"type":"string"}}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The products of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Related Products of a Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Related Products of a Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/products/{product_id}/relationships/{custom_relationship_slug}/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns related products of the provided product ID from a published catalog.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","style":"simple","schema":{"type":"array","items":{"type":"string"},"maxItems":5}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","style":"simple","schema":{"type":"array","items":{"type":"string"}}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The custom relationship slug.","name":"custom_relationship_slug","in":"path","required":true,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The related products of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Hierarchies(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Hierarchies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/hierarchies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all hierarchies from a catalog.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).

| Operator | Description | Supported Attributes | Example |
|:--- |:--- |:--- |:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug`| `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. | `id` | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"\nThis endpoints supports filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The hierarchies of the catalog.","content":{"application/json":{"schema":{"type":"object","title":"HierarchyListData","description":"Container for a list of hierarchies.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Hierarchy","description":"A category hierarchy in a catalog. Hierarchies can have parent nodes and child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"HierarchyAttributes","description":"Resource attributes of a catalog hierarchy.","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a hierarchy is published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"description":"A description of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Description"},"name":{"description":"The name of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A unique slug for a hierarchy.","type":"string","example":"formal","x-go-name":"Slug"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a hierarchy was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"HierarchyAttributes"},"id":{"description":"A unique identifier of a hierarchy.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"HierarchyRelationships","description":"Relationships to child nodes, and products.","properties":{"products":{"description":"A URL to all the products associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all the child products associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"nodes":{"description":"A URL to all the nodes associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]}},"x-go-name":"HierarchyRelationships"},"type":{"description":"This represents the type of object being returned. Always `hierarchy`.","type":"string","example":"hierarchy","x-go-name":"Type"},"meta":{"type":"object","title":"HierarchyMeta","description":"A hierarchy's metadata.","properties":{"language":{"description":"Product Experience Manager supports localization of hierarchies. If your store supports multiple languages, you can localize hierarchy names and descriptions. This is [**three-letter language code**](https://www.iso.org/iso-639-language-code) that represents the name of the language you have used.","type":"string","example":"en-GB"},"breadcrumbs":{"description":"Hierarchy Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"HierarchyBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"HierarchyMeta","x-omitempty":true}},"x-go-name":"Hierarchy"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"An unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Nodes(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Nodes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all nodes in the catalog.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a node is associated with in the `breadcrumbs` metadata for each node. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

In a catalog, you can use a filter to return a list of nodes in a hierarchy structure that a product belongs to. You can use this to build breadcrumbs in your storefront. For more information, see [Building breadcrumbs in a storefront](#building-breadcrumbs-in-a-storefront).

The response lists the products associated with the nodes. If products are [curated](/guides/How-To/Products/curating-products), they are displayed in `curated_products`. Product curation allows you to promote specific products within each of your hierarchies, enabling you to create unique product collections in your storefront.

- You can only curate 20 products or less. You cannot have more than 20 curated products.
- If a curated product is removed from a node, the product is also removed from the `curated_products` list.

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available.

| Operator  | Description | Attributes | Example |
| --- | --- | --- | --- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug` | `filter=eq(name,some-name)` |
| `in`      | Checks if the values are included in the specified string. If they are, the condition is true.
| `Id` |  `filter=in(id,9214719b-17fe-4ea7-896c-d61e60fc0d05,e104d541-2c52-47fa-8a9a-c4382480d97c,65daaf68-ff2e-4632-8944-370de835967d)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The nodes of the catalog.","content":{"application/json":{"schema":{"type":"object","title":"NodeListData","description":"Container for a list of nodes.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"An unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Products(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the list of products from the catalog. Only the products in a live status are retrieved.

### Catalog Rules

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. If no catalog rules are configured, the first catalog found is returned. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

### Product and Node Associations

 You can see the parent nodes a product is associated within the `bread_crumbs` and `bread_crumb_nodes` metadata for each product. For example, this is useful if you want to improve how your shoppers search your store. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. For `product_types` and `tags`, you can only specify one. For example, `filter=eq(product_types,child)`.            | `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags` | `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. For `product_types` and `tags`, you can specify more than one. For example, `filter=in(product_types,child,bundle)`. | `id`, `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags`          | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The products of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Related Products of a Product(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Related Products of a Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/products/{product_id}/relationships/{custom_relationship_slug}/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns related products of the provided product ID from a catalog.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The custom relationship slug.","name":"custom_relationship_slug","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The related products of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Node's Children

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Node's Children"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/nodes/{node_id}/relationships/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the child nodes for a node in the catalog.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see which parent nodes a node is associated with in the `breadcrumbs` metadata for each node. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

The response lists the products associated with the nodes. If products are [curated](/guides/How-To/Products/curating-products), they are displayed in `curated_products`. Product curation allows you to promote specific products within each of your hierarchies, enabling you to create unique product collections in your storefront.

- If you don't provide any curated_products, products are listed by their updated_at time in descending order, with the most recently updated product first.
- If you configure curated_products for only a few products, the curated products are displayed first and the other products are displayed in the order of updated_at time.
- You can only curate 20 products or less. You cannot have more than 20 curated products.
- A product that is curated has the "curated_product": true attribute displayed.
- If a curated product is removed from a node, the product is also removed from the curated_products list.

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available.

| Operator  | Description | Attributes | Example |
| --- | --- | --- | --- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug` | `filter=eq(name,some-name)` |
| `in`      | Checks if the values are included in the specified string. If they are, the condition is true.
| `Id` |  `filter=in(id,9214719b-17fe-4ea7-896c-d61e60fc0d05,e104d541-2c52-47fa-8a9a-c4382480d97c,65daaf68-ff2e-4632-8944-370de835967d)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}},{"description":"The catalog node ID.","name":"node_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The child nodes of a catalog node.","content":{"application/json":{"schema":{"type":"object","title":"NodeListData","description":"Container for a list of nodes.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Parent Product's Child Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Parent Product's Child Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/products/{product_id}/relationships/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

For a specified product and catalog release, retrieves a list of child products from a parent product. Any product other than a base product results in a `422 Unprocessable Entity` response. Only the products in a `live` status are retrieved.

If you have multiple catalog rules defined, the rule that best matches the shopperʼs context is used to determine which catalog is retrieved. If no catalog rules are configured, the first catalog found is returned. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a product is associated within the `breadcrumbs` metadata for each product. For example, this is useful if you want to improve how your shoppers search your store. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. For `product_types` and `tags`, you can only specify one. For example, `filter=eq(product_types,child)`.            | `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags` | `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. For `product_types` and `tags`, you can specify more than one. For example, `filter=in(product_types,child,bundle)`. | `id`, `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags`          | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of child products of a parent product from a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Bundle's Component Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Bundle's Component Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/products/{product_id}/relationships/component_products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

With Product Experience Manager, you can [create](/docs/api/pxm/products/create-product) and manage bundles. A bundle is a purchasable product, comprising of one or more products that you want to sell together. 

You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.

This endpoint returns a list of component product IDs for the specified bundle.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of component product IDs of a bundle product from a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductReferenceListData","description":"Container for a list of product references.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Hierarchy's Children

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Hierarchy's Children"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/hierarchies/{hierarchy_id}/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the parent nodes for the specified hierarchy.

![Parent Nodes](/assets/rootnodes.PNG)

If you have multiple catalog rules defined, the rule that best matches the shopperʼs context is used to determine which catalog is retrieved. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

In the `breadcrumbs` metadata, you can identify the parent nodes that a node is associated with. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Filtering

The following operators and attributes are available when filtering on this endpoint.

| Operator | Description | Supported Attributes | Example |
|:--- |:--- |:--- |:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug`| `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. | `id` | `filter=in(id,some-id)` |

For more information, see [Filtering](/guides/Getting-Started/filtering).

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}},{"description":"The catalog hierarchy ID.","name":"hierarchy_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The child nodes of a catalog hierarchy.","content":{"application/json":{"schema":{"type":"object","title":"NodeListData","description":"Container for a list of nodes.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Hierarchy's Nodes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Hierarchy's Nodes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/hierarchies/{hierarchy_id}/nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all the nodes for the specified hierarchy.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

In the `breadcrumbs` metadata, you can identify the parent nodes that a node is associated with. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).

| Operator | Description | Supported Attributes | Example |
|:--- |:--- |:--- |:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug`| `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. | `id` | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}},{"description":"The catalog hierarchy ID.","name":"hierarchy_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The child nodes of a catalog hierarchy.","content":{"application/json":{"schema":{"type":"object","title":"NodeListData","description":"Container for a list of nodes.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Hierarchy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Hierarchy"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/hierarchies/{hierarchy_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a hierarchy from the catalog.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog to retrieve. For information about how catalog rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"description":"The catalog hierarchy ID.","name":"hierarchy_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The catalog hierarchy.","content":{"application/json":{"schema":{"type":"object","title":"HierarchyData","description":"Container for hierarchies.","properties":{"data":{"type":"object","title":"Hierarchy","description":"A category hierarchy in a catalog. Hierarchies can have parent nodes and child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"HierarchyAttributes","description":"Resource attributes of a catalog hierarchy.","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a hierarchy is published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"description":"A description of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Description"},"name":{"description":"The name of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A unique slug for a hierarchy.","type":"string","example":"formal","x-go-name":"Slug"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a hierarchy was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"HierarchyAttributes"},"id":{"description":"A unique identifier of a hierarchy.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"HierarchyRelationships","description":"Relationships to child nodes, and products.","properties":{"products":{"description":"A URL to all the products associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all the child products associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"nodes":{"description":"A URL to all the nodes associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]}},"x-go-name":"HierarchyRelationships"},"type":{"description":"This represents the type of object being returned. Always `hierarchy`.","type":"string","example":"hierarchy","x-go-name":"Type"},"meta":{"type":"object","title":"HierarchyMeta","description":"A hierarchy's metadata.","properties":{"language":{"description":"Product Experience Manager supports localization of hierarchies. If your store supports multiple languages, you can localize hierarchy names and descriptions. This is [**three-letter language code**](https://www.iso.org/iso-639-language-code) that represents the name of the language you have used.","type":"string","example":"en-GB"},"breadcrumbs":{"description":"Hierarchy Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"HierarchyBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"HierarchyMeta","x-omitempty":true}},"x-go-name":"Hierarchy"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Node

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Node"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/nodes/{node_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a node from the catalog.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a node is associated with in the `breadcrumbs` metadata for each node. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

The response lists the products associated with a node. If products are [curated](/guides/How-To/Products/curating-products), they are displayed in `curated_products`. Product curation allows you to promote specific products within each of your nodes, enabling you to create unique product collections in your storefront.

- If you don't provide any `curated_products`, products are listed by their `updated_at` time in descending order, with the most recently updated product first.
- If you configure `curated_products` for only a few products, the curated products are displayed first and the other products are displayed in the order of `updated_at` time.
- You can only curate 20 products or less. You cannot have more than 20 curated products.
- A product that is curated has the `"curated_product": true` attribute displayed.
- If a curated product is removed from a node, the product is also removed from the `curated_products` list.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The catalog node ID.","name":"node_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The catalog node.","content":{"application/json":{"schema":{"type":"object","title":"NodeData","description":"Container for nodes.","properties":{"data":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/products/{product_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the specified product from the catalog. The product must be in the `live` status.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a product is associated with in the `bread_crumbs` and `bread_crumb_nodes` metadata for each product. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                       |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The product of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductData","description":"Container for products.","properties":{"data":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Hierarchy's Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Hierarchy's Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/hierarchies/{hierarchy_id}/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the products associated with the specified hierarchy in the catalog. The products must be in the live status.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. See [Resolving catalog rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a product is associated with in the `bread_crumbs` and `bread_crumb_nodes` metadata for each product. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. For `product_types` and `tags`, you can only specify one. For example, `filter=eq(product_types,child)`.            | `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags` | `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. For `product_types` and `tags`, you can specify more than one. For example, `filter=in(product_types,child,bundle)`. | `id`, `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags`          | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
   `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}},{"description":"The catalog hierarchy ID.","name":"hierarchy_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The products of a catalog hierarchy.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Node's Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Node's Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog/nodes/{node_id}/relationships/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the products associated with the specified hierarchy node in the catalog. The products must be in the `live` status. If the products have been curated then the products are returned in the order specified in the `curated_products` attribute. A product that is curated has the `"curated_product": true` attribute displayed.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. See [Resolving catalog rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a product is associated with in the `bread_crumbs` and `bread_crumb_nodes` metadata for each product. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. For `product_types` and `tags`, you can only specify one. For example, `filter=eq(product_types,child)`.            | `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags` | `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. For `product_types` and `tags`, you can specify more than one. For example, `filter=in(product_types,child,bundle)`. | `id`, `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags`          | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug.

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The catalog node ID.","name":"node_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The products of a catalog node.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get the catalog release as shoppers

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get the catalog release as shoppers"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalog"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a list of all published releases of the specified catalog.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","required":false,"schema":{"type":"string"}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","required":false,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The catalog.","content":{"application/json":{"schema":{"type":"object","title":"Release Data","description":"Container for a catalog release.","properties":{"data":{"type":"object","title":"Release","description":"A catalog release represents a collection of hierarchical product data, price books and catalogs rules.","properties":{"id":{"description":"A unique identifier for the catalog release.","type":"string","x-go-name":"ID","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a release.","type":"string","example":"Clothing"},"published_at":{"description":"The date and time a release was published.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"catalog_id":{"description":"A unique identifier for the catalog.","type":"string","example":"0194f54d-f2a1-4e33-9a6e-9ec366152490"},"description":{"description":"A description of the catalog release.","type":"string","example":"Catalog for Store 123","default":""},"hierarchies":{"description":"An array of hierarchy IDs associated with the release.","type":"array","items":{"type":"object","title":"NodeReference","description":"Minimum set of information to identify a catalog node.","properties":{"id":{"description":"The unique identifier of a hierarchy.","type":"string","example":"65477ce0-fcb8-436b-a120-3d57979421dd","x-go-name":"ID"},"label":{"description":"A label for a hierarchy.","type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Name"}},"x-go-name":"NodeReference"},"x-go-name":"RootNodes"}}},"relationships":{"type":"object","title":"ReleaseRelationships","description":"Relationships are established between different catalog entities. For example, products, hierarchies, price books, and catalog rules are related to a catalog, as they are associated with it.","properties":{"delta":{"description":"A URL to a delta document that describes the changes between catalog releases.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"products":{"description":"A URL to all products included in a catalog release.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"hierarchies":{"description":"A URL to all hierarchies included in a catalog release.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]}},"x-go-name":"ReleaseRelationships"},"type":{"description":"This represents the type of object being returned. Always `catalog-release`.","type":"string","x-go-name":"Type"},"meta":{"type":"object","title":"ReleaseMeta","description":"A release's metadata.","properties":{"created_at":{"description":"The date and time a release is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000"},"started_at":{"description":"The date and time a release is available for use. In other words, the date and time the status of a catalog release changes to PUBLISHED, rather than IN PROGRESS.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"updated_at":{"description":"The date and time a release is updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"release_status":{"description":"The status of the current release.","type":"string","enum":["PENDING","IN_PROGRESS","FAILED","PUBLISHED"]},"language":{"description":"Your storefront's preferred language code and locale.","type":"string","example":"en-GB"},"is_full_publish":{"description":"Indicates that a full publish was performed (either because this is the first time a catalog has been published or because of a change that occurred, for example, adding/removing a price book or hierarchy). When determining whether delta data needs to be refreshed, ignore this attribute and always use the `is_full_delta` attribute.\n","type":"boolean","example":false,"default":false,"x-go-name":"IsFullPublish"},"is_full_delta":{"description":"Indicates whether the release delta file contains the full content of a catalog release. Using a search service as an example, if the `is_full_delta` attribute is `true`, you should remove all data about that catalog release from the search service before injecting fresh data from the delta file. If the `is_full_delta` attribute is `false`, then data from the previous catalog release overlays the existing data in the delta file. The `is_full_delta` attribute is always `true` the first time a catalog is published.\n","type":"boolean","example":false,"default":false,"x-go-name":"IsFullDelta"},"total_products":{"description":"The total number of products displayed in a catalog release.","type":"integer","format":"int64","x-go-name":"TotalProducts","nullable":true},"total_nodes":{"description":"The total number of hierarchy nodes displayed in a catalog release.","type":"integer","format":"int64","x-go-name":"TotalNodes","nullable":true},"percent_completed":{"description":"An integer that represents the progress of a catalog publish. The attribute starts at `0` and reaches `100` when publishing is complete.","type":"integer","format":"int32","x-go-name":"PercentCompleted","nullable":true},"owner":{"description":"The owner of the resource, can be either `organization` or `store`.","type":"string","enum":["store","organization"],"x-go-name":"Owner","nullable":true},"price_segmentation_enabled":{"description":"This indicates whether the catalog release will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean"},"includes_draft_products":{"description":"When `true`, this catalog release includes `draft` products in its published data. This reflects the catalog `include_draft_products` attribute at the time of publish.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesDraftProducts"}},"x-go-name":"ReleaseMeta","x-omitempty":true}},"x-go-name":"Release"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a catalog by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a catalog by ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the specified catalog.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The catalog.","content":{"application/json":{"schema":{"type":"object","title":"CatalogData","description":"Container for a single catalog.","properties":{"data":{"type":"object","title":"Catalog","description":"Creates a catalog with the following attributes.","properties":{"id":{"type":"string","description":"A unique identifier of a catalog.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog.","type":"string","example":"catalog-123"},"description":{"description":"A brief description of the catalog, such as the purpose of the catalog.","type":"string","example":"Catalog for Store 123","default":""},"hierarchy_ids":{"description":"The unique identifiers of the hierarchies associated with a catalog.","type":"array","items":{"type":"string"}},"pricebook_id":{"description":"The unique identifier of a price book associated with a catalog. If no price book is selected, the catalog is displayed without prices.","type":"string"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"string"}}},"created_at":{"description":"The date and time a catalog is created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog was updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"owner":{"description":"The owner of this resource, can be either `organization` or `store`.","type":"string","enum":["store","organization"],"x-go-name":"Owner","default":"store","nullable":true},"enable_price_segmentation":{"description":"This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean","example":true,"default":false,"x-go-name":"EnablePriceSegmentation"},"include_draft_products":{"description":"When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).","type":"boolean","example":false,"default":false,"x-go-name":"IncludeDraftProducts"}},"required":["name","hierarchy_ids","created_at","updated_at"]},"relationships":{"description":"Relationships are established between different catalog entities. For example, a catalog rule and a price book are related to a catalog, as both are associated with it.","type":"object","title":"CatalogRelationships","properties":{"rules":{"description":"The catalog rules related to a catalog.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"releases":{"description":"When a catalog is published, a catalog release is created. This is a URL to all catalog published releases available for this catalog.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"},"meta":{"type":"object","properties":{"count":{"description":"The number releases available for a catalog.","type":"integer"}}}}}}},"type":{"type":"string","example":"catalog","enum":["catalog"]}},"required":["id","type","attributes"]},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"An unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Gets all authorized catalogs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Gets all authorized catalogs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all the catalogs that you are authorized to view. Currently, published catalogs are limited to the current release and two releases prior to the current release. You can see the differences between the last 2 consecutive catalog releases using the delta link returned in the response of a [publish a catalog](/docs/api/pxm/catalog/publish-release) endpoint.

You can use the `is_full_delta` attribute returned from the `get a release of a catalog` endpoint to determine if you need to refresh the data in your company system before publishing a catalog release and injecting fresh data in a delta link. The `is_full_delta` attribute tells you if this is a full publish of a catalog release. Using a search service as an example, if the `is_full_delta` attribute is `true`, you should remove all data about that catalog from the search service before publishing a catalog release and injecting fresh data from the delta file. See [Publish a catalog](/docs/api/pxm/catalog/publish-release).

If the `is_full_publish` attribute returned in the response is `false`, data from the previous catalog release overlaid the existing data in the delta file. The `is_full_publish` attribute is always `true` the first time a catalog is published. When determining whether delta data needs to be refreshed, ignore this attribute and always use the `is_full_delta` attribute.

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `eq` | Checks if the values of two operands are equal. If they are, the condition is true.       | `name`, | `filter=eq(name,some-name)` |
| `in` | Checks if the values are included in the specified list. If they are, the condition is true. | `name`   | `filter=in(name,some-name,some-name2)` |
| `like` | Checks if the operand contains the specified string. Wildcards are supported | `name`          | `filter=like(name,*some-name*)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of catalogs.","content":{"application/json":{"schema":{"type":"object","title":"CatalogListData","description":"Container for a list of catalogs.","properties":{"data":{"type":"array","items":{"type":"object","title":"Catalog","description":"Creates a catalog with the following attributes.","properties":{"id":{"type":"string","description":"A unique identifier of a catalog.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog.","type":"string","example":"catalog-123"},"description":{"description":"A brief description of the catalog, such as the purpose of the catalog.","type":"string","example":"Catalog for Store 123","default":""},"hierarchy_ids":{"description":"The unique identifiers of the hierarchies associated with a catalog.","type":"array","items":{"type":"string"}},"pricebook_id":{"description":"The unique identifier of a price book associated with a catalog. If no price book is selected, the catalog is displayed without prices.","type":"string"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"string"}}},"created_at":{"description":"The date and time a catalog is created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog was updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"owner":{"description":"The owner of this resource, can be either `organization` or `store`.","type":"string","enum":["store","organization"],"x-go-name":"Owner","default":"store","nullable":true},"enable_price_segmentation":{"description":"This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean","example":true,"default":false,"x-go-name":"EnablePriceSegmentation"},"include_draft_products":{"description":"When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).","type":"boolean","example":false,"default":false,"x-go-name":"IncludeDraftProducts"}},"required":["name","hierarchy_ids","created_at","updated_at"]},"relationships":{"description":"Relationships are established between different catalog entities. For example, a catalog rule and a price book are related to a catalog, as both are associated with it.","type":"object","title":"CatalogRelationships","properties":{"rules":{"description":"The catalog rules related to a catalog.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"releases":{"description":"When a catalog is published, a catalog release is created. This is a URL to all catalog published releases available for this catalog.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"},"meta":{"type":"object","properties":{"count":{"description":"The number releases available for a catalog.","type":"integer"}}}}}}},"type":{"type":"string","example":"catalog","enum":["catalog"]}},"required":["id","type","attributes"]}},"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"An unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Node's Children(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Node's Children"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/nodes/{node_id}/relationships/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the child nodes for a node from a published catalog.

:::note

Currently, published catalogs are limited to the current release and two releases prior to the current release.

:::

You can see the parent nodes a node is associated with in the `breadcrumbs` metadata for each node. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

In a catalog, you can use a filter to return a list of nodes in a hierarchy structure that a product belongs to. You can use this to build breadcrumbs in your storefront. For more information, see [Building breadcrumbs in a storefront](#building-breadcrumbs-in-a-storefront).

The response lists the products associated with the nodes. If products are [curated](/guides/How-To/Products/curating-products), they are displayed in `curated_products`. Product curation allows you to promote specific products within each of your hierarchies, enabling you to create unique product collections in your storefront.

- If you don't provide any `curated_products`, products are listed by their `updated_at` time in descending order, with the most recently updated product first.
- If you configure `curated_products` for only a few products, the curated products are displayed first and the other products are displayed in the order of `updated_at` time.
- You can only curate 20 products or less. You cannot have more than 20 curated products.
- If a curated product is removed from a node, the product is also removed from the `curated_products` list.
- A product that is curated has the `"curated_product": true` attribute displayed.

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available.

| Operator  | Description | Attributes | Example |
| --- | --- | --- | --- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug` | `filter=eq(name,some-name)` |
| `in`      | Checks if the values are included in the specified string. If they are, the condition is true.
| `Id` |  `filter=in(id,9214719b-17fe-4ea7-896c-d61e60fc0d05,e104d541-2c52-47fa-8a9a-c4382480d97c,65daaf68-ff2e-4632-8944-370de835967d)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The catalog node ID.","name":"node_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The child nodes of a catalog node.","content":{"application/json":{"schema":{"type":"object","title":"NodeListData","description":"Container for a list of nodes.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Parent Product's Child Products(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Parent Product's Child Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/products/{product_id}/relationships/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

For a specified product and catalog release, retrieves a list of child products from a parent product. Any product other than a base product results in a `422 Unprocessable Entity` response. Only the products in a `live` status are retrieved.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. If no catalog rules are configured, the first catalog found is returned. For information about how rules are matched, see [Resolving Catalog Rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a product is associated within the breadcrumbs metadata for each product. For example, this is useful if you want to improve how your shoppers search your store. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. For `product_types`, you can only specify one product type. For example, `filter=eq(product_types,child)`.            | `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags` | `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. For `product_types`, you can specify more than one product type. For example, `filter=in(product_types,child,bundle)`. | `id`, `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags`          | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","style":"simple","schema":{"type":"array","items":{"type":"string"},"maxItems":5}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","style":"simple","schema":{"type":"array","items":{"type":"string"}}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of child products of a specific base product from a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Bundle's Component Products(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Bundle's Component Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/products/{product_id}/relationships/component_products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

With Product Experience Manager, you can [create](/docs/api/pxm/products/create-product) and manage bundles. A bundle is a purchasable product, comprising of one or more products that you want to sell together. 

You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.

This endpoint returns a list of component product IDs for the specified bundle.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","style":"simple","schema":{"type":"array","items":{"type":"string"},"maxItems":5}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","style":"simple","schema":{"type":"array","items":{"type":"string"}}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of component product IDs of a specific bundle product from a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductReferenceListData","description":"Container for a list of product references.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Hierarchy's Children(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Hierarchy's Children"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/hierarchies/{hierarchy_id}/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the parent nodes for the specified hierarchy from a published catalog.

![Parent Nodes](/assets/rootnodes.PNG)

:::note

Currently, published catalogs are limited to the current release and two releases prior to the current release.

:::

In the `breadcrumbs` metadata, you can identify the parent nodes that a node is associated with. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).

| Operator | Description | Supported Attributes | Example |
|:--- |:--- |:--- |:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug`| `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. | `id` | `filter=in(id,some-id)` | 

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The catalog hierarchy ID.","name":"hierarchy_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The child nodes of a catalog hierarchy.","content":{"application/json":{"schema":{"type":"object","title":"NodeListData","description":"Container for a list of nodes.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Hierarchy's Nodes(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Hierarchy's Nodes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/hierarchies/{hierarchy_id}/nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all nodes for the specified hierarchy from a published catalog.

:::note

Currently, published catalogs are limited to the current release and two releases prior to the current release.

:::

In the `breadcrumbs` metadata, you can identify the parent nodes that a node is associated with. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).

| Operator | Description | Supported Attributes | Example |
|:--- |:--- |:--- |:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. | `name`, `slug`| `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. | `id` | `filter=in(id,some-id)` | 

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The catalog hierarchy ID.","name":"hierarchy_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoint supports filtering, see [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The child nodes of a catalog hierarchy.","content":{"application/json":{"schema":{"type":"object","title":"NodeListData","description":"Container for a list of nodes.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Hierarchy(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Hierarchy"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/hierarchies/{hierarchy_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the specified hierarchy from a published catalog.

:::note

Currently, published catalogs are limited to the current release and two releases prior to the current release.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The catalog hierarchy ID.","name":"hierarchy_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The catalog hierarchy.","content":{"application/json":{"schema":{"type":"object","title":"HierarchyData","description":"Container for hierarchies.","properties":{"data":{"type":"object","title":"Hierarchy","description":"A category hierarchy in a catalog. Hierarchies can have parent nodes and child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"HierarchyAttributes","description":"Resource attributes of a catalog hierarchy.","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a hierarchy is published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"description":"A description of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Description"},"name":{"description":"The name of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A unique slug for a hierarchy.","type":"string","example":"formal","x-go-name":"Slug"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a hierarchy was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"HierarchyAttributes"},"id":{"description":"A unique identifier of a hierarchy.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"HierarchyRelationships","description":"Relationships to child nodes, and products.","properties":{"products":{"description":"A URL to all the products associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all the child products associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"nodes":{"description":"A URL to all the nodes associated with a hierarchy.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]}},"x-go-name":"HierarchyRelationships"},"type":{"description":"This represents the type of object being returned. Always `hierarchy`.","type":"string","example":"hierarchy","x-go-name":"Type"},"meta":{"type":"object","title":"HierarchyMeta","description":"A hierarchy's metadata.","properties":{"language":{"description":"Product Experience Manager supports localization of hierarchies. If your store supports multiple languages, you can localize hierarchy names and descriptions. This is [**three-letter language code**](https://www.iso.org/iso-639-language-code) that represents the name of the language you have used.","type":"string","example":"en-GB"},"breadcrumbs":{"description":"Hierarchy Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"HierarchyBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"HierarchyMeta","x-omitempty":true}},"x-go-name":"Hierarchy"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Node(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Node"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/nodes/{node_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a node from a published catalog.

:::note

Currently, published catalogs are limited to the current release and two releases prior to the current release.

:::

You can see the parent nodes a node is associated with in the `breadcrumbs` metadata for each node. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

The response lists the products associated with the nodes. If products are [curated](/guides/How-To/Products/curating-products), they are displayed in `curated_products`. Product curation allows you to promote specific products within each of your hierarchies, enabling you to create unique product collections in your storefront.

- If you don't provide any `curated_products`, products are listed by their `updated_at` time in descending order, with the most recently updated product first.
- If you configure `curated_products` for only a few products, the curated products are displayed first and the other products are displayed in the order of `updated_at` time.
- You can only curate 20 products or less. You cannot have more than 20 curated products.
- If a curated product is removed from a node, the product is also removed from the `curated_products` list.
- A product that is curated has the `"curated_product": true` attribute displayed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The catalog node ID.","name":"node_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The catalog node.","content":{"application/json":{"schema":{"type":"object","title":"NodeData","description":"Container for nodes.","properties":{"data":{"type":"object","title":"Node","description":"A category node in a catalog. Nodes can have child nodes, as well as a list of attached products.","properties":{"attributes":{"type":"object","title":"NodeAttributes","description":"Resource attributes of a catalog node.","properties":{"created_at":{"description":"The date and time a node was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"published_at":{"description":"The date and time a node was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"description":{"type":"string","description":"A description of a node.","example":"Formal dresswear","x-go-name":"Description"},"label":{"type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a node. Names must be unique among sibling nodes in a hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"Formal dresswear","x-go-name":"Name"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string","example":"formal","x-go-name":"Slug"},"curated_products":{"description":"A list of curated products for a node. You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"status":{"type":"string","example":"live","x-go-name":"Status"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"updated_at":{"description":"The date and time a node was updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"UpdatedAt"}},"x-go-name":"NodeAttributes"},"id":{"description":"The unique identifier of a node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-go-name":"ID"},"relationships":{"type":"object","title":"NodeRelationships","description":"Relationships to parent and child nodes, and products.","properties":{"products":{"description":"A URL to all products associated with a node.","type":"object","properties":{"data":{"type":"array","x-omitempty":true,"items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"children":{"description":"A URL to all child nodes associated with a node.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]},"parent":{"description":"A URL to all parent nodes associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"node","enum":["node"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]},"hierarchy":{"description":"A URL to the hierarchies associated with a node.","type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"hierarchy","enum":["hierarchy"]},"id":{"type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"}},"required":["id","type"]},"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["data"]}},"x-go-name":"NodeRelationships"},"type":{"description":"This represents the type of object being returned. Always `node`.","type":"string","example":"node","x-go-name":"Type"},"meta":{"type":"object","title":"NodeMeta","description":"A node's metadata.","properties":{"language":{"description":"The node details localized in the supported languages.","type":"string","example":"en-GB"},"bread_crumb":{"description":"Helps you understand the association of products with nodes. It explains how products are associated with parent nodes and the relationship among the array of nodes. This is useful if you want to improve how your shoppers search within you store.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true,"deprecated":true},"breadcrumbs":{"description":"Node Breadcrumbs","type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string","example":"e871df93-c769-49a9-9394-a6fd555b8e8a","x-omitempty":true},"name":{"description":"The name of the hierarchy/node.","type":"string","example":"Formal dresswear","x-omitempty":true},"slug":{"description":"A slug for the hierarchy/node.","type":"string","example":"formal","x-omitempty":true}},"x-go-name":"NodeBreadcrumb"},"x-omitempty":true},"has_children":{"description":"Indicates whether a node has child nodes. `true` if the node has at least one child, `false` if it has none.","type":"boolean","example":true,"x-go-name":"HasChildren","x-omitempty":true,"nullable":true}},"x-go-name":"NodeMeta","x-omitempty":true}},"x-go-name":"Node"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Product(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/products/{product_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a product from a published catalog. The product must be in `live` status. Currently, published catalogs are limited to the current release and two releases prior to the current release.

### Product and Node Associations in Breadcrumb Metadata

You can see the parent nodes a product is associated with in the `bread_crumbs` and `bread_crumb_nodes` metadata for each product. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

### Product Variations

The `variations` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. The `variations` object can then be added to your catalogs. By default, variations and variation options are sorted randomly. You can use the `sort_order`attribute to sort the order of your variation and variation options in `variations`. Once a parent product is published in a catalog, the get a product in a catalog release response displays the sorted variations and variation options. Variations and variation options are displayed in descending order according to their `sort_order` values.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter          | Required | Description                                                                                                                                                                                                           |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product.                                                                                                           |
| `files`              | Optional | Any files associated with a product. 

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","style":"simple","schema":{"type":"array","items":{"type":"string"},"maxItems":5}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","style":"simple","schema":{"type":"array","items":{"type":"string"}}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The product ID.","name":"product_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The product of a catalog.","content":{"application/json":{"schema":{"type":"object","title":"ProductData","description":"Container for products.","properties":{"data":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Hierarchy's Products(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Hierarchy's Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/hierarchies/{hierarchy_id}/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the products associated with the specified hierarchy in the catalog. The products must be in the `live` status.

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. See [Resolving catalog rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a product is associated with in the `bread_crumbs` and `bread_crumb_nodes` metadata for each product. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

The `variations` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. The variations object can then be added to your catalogs. By default, variations and variation options are sorted randomly. You can use the `sort_order` attribute to sort the order of your variation and variation options in variations. Once a parent product is published in a catalog, the [Get a List of products in a catalog](/docs/api/pxm/catalog/get-all-products) release response displays the sorted variations and variation options. Variations and variation options are displayed in descending order according to their `sort_order` values.

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. For `product_types`, you can only specify one product type. For example, `filter=eq(product_types,child)`.          | `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags` | `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. For `product_types`, you can specify more than one product type. For example, `filter=in(product_types,child,bundle)`. | `id`, `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags`          | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","style":"simple","schema":{"type":"array","items":{"type":"string"},"maxItems":5}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","style":"simple","schema":{"type":"array","items":{"type":"string"}}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The catalog hierarchy ID.","name":"hierarchy_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The products of a catalog hierarchy.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Node's Products(Catalog)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Node's Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}/nodes/{node_id}/relationships/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the products associated with the specified hierarchy node in the catalog. The products must be in the `live` status. If the products have been curated, then the products are returned in the order specified in the `curated_products` attribute. A product that is curated has the `"curated_product": true` attribute displayed.

:::note

Currently, published catalogs are limited to the current release and two releases prior to the current release.

:::

If you have multiple catalog rules defined, the rule that best matches the shoppers context is used to determine which catalog is retrieved. See [Resolving catalog rules](/docs/api/pxm/catalog/rules#resolving-catalog-rules).

You can see the parent nodes a product is associated with in the `bread_crumbs` and `bread_crumb_nodes` metadata for each product. This is useful if you want to improve how your shoppers search your store, for example. See [Product and Node Associations in Breadcrumb Metadata](/guides/How-To/Catalogs/breadcrumbs).

The `variations` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. The `variations` object can then be added to your catalogs. By default, variations and variation options are sorted randomly. You can use the `sort_order` attribute to sort the order of your variation and variation options in `variations`. Once a parent product is published in a catalog, the [Get a List of products in a catalog release](/docs/api/pxm/catalog/get-all-products) response displays the sorted variations and variation options. Variations and variation options are displayed in descending order according to their `sort_order` values.

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are available when filtering on this endpoint.

| Operator | Description                                                                                     | Supported Attributes                                     | Example |
|:---|:------------------------------------------------------------------------------------------------|:---------------------------------------------------------|:--- |
| `Eq` | Checks if the values of two operands are equal. If they are, the condition is true. For `product_types` and `tags`, you can only specify one. For example, `filter=eq(product_types,child)`.          | `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags` | `filter=eq(name,some-name)` |
| `In` | Checks if the values are included in the specified string. If they are, the condition is true. For `product_types` and `tags`, you can specify more than one. For example, `filter=in(product_types,child,bundle)`. | `id`, `name`, `sku`, `slug`, `manufacturer_part_num`, `upc_ean`, `product_types`, `tags`          | `filter=in(id,some-id)` |

### Building breadcrumbs in a storefront

In a catalog, you can use the nodes directly attached to a product to build breadcrumbs in your storefront. This eliminates the need for additional queries to fetch hierarchy or parent node details. Each node contains all the necessary information in `breadcrumbs` metadata, such as its own details and the details of its parent hierarchy/node(s), to construct the complete breadcrumb path without requiring additional queries.

An example is shown below:

`filter=in(id,c83bfe55-0d87-4302-a86d-ab19e7e323f1,6003d7ef-84f3-49bb-a8bd-4cbfa203dcbb)`

- Specify the node IDs directly attached to the product in the filter expression.
- You can include as many node IDs as required.
- It does not matter what order you specify the node IDs. The nodes are returned in the order they were last updated.

### Including Resources

Using the `include` parameter, you can retrieve top-level resources, such as, files or main image, bundle component products and product attributes, such as SKU or slug. 

| Parameter | Required | Description                                                                                                                                                                                                    |
|  :---------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component_products` | Optional | The  component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.  |
| `main_image`         | Optional | The main images associated with a product. |
| `files`              | Optional | Any files associated with a product. |

See [**Including Resources**](/guides/Getting-Started/includes).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"name":"filter","in":"query","description":"This endpoints support filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]}}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","style":"simple","schema":{"type":"array","items":{"type":"string"},"maxItems":5}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","style":"simple","schema":{"type":"array","items":{"type":"string"}}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The catalog node ID.","name":"node_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The products of a catalog node.","content":{"application/json":{"schema":{"type":"object","title":"ProductListData","description":"Container for a list of products.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"},"x-go-name":"Data"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","title":"ProductAttributes","description":"A product's attributes.","properties":{"published_at":{"description":"The date and time a product was published in a catalog.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"base_product":{"description":"If this product is a `parent` product. A `parent` product is a product that has child products that have been built using the `build child products` endpoint.","type":"boolean","example":false,"default":false,"x-go-name":"BaseProduct"},"base_product_id":{"description":"The unique identifier of a `parent` product.","type":"string","example":"cdf574bc-e36e-48fc-9eac-01c87839b285","x-go-name":"BaseProductID"},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","example":"physical","x-go-name":"CommodityType"},"curated_product":{"description":"If a product is curated, then the `curated_product` attribute with a value of `true` is displayed. If a product is not curated, the `curated_product` attribute is not displayed.","type":"boolean","example":true,"x-omitempty":true,"x-go-name":"CuratedProduct"},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string","example":"0123456","x-go-name":"UpcEan"},"manufacturer_part_num":{"description":"The manufacturer part number of the product.","type":"string","example":"mfn1","x-go-name":"ManufacturerPartNum"},"tags":{"type":"array","description":"A list of tags associated with the product. A tag must be HTML compatible characters excluding commas and will be stored in lowercase letters.","items":{"description":"A tag associated with the product.","type":"string","example":"tag-a"},"x-go-name":"Tags","x-omitempty":true},"price_modifiers":{"type":"array","description":"A list of price modifier names.","items":{"description":"A list of price modifier names.","type":"string","example":"modifier-1"},"x-go-name":"PriceModifiers","x-omitempty":true},"created_at":{"description":"The date and time a product was created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"},"description":{"description":"A description of the product.","type":"string","example":"This is a product","x-go-name":"Description"},"name":{"description":"A name of a product.","type":"string","example":"Blue shirt","x-go-name":"Name"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}},"components":{"type":"object","title":"Components","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","additionalProperties":{"type":"object","title":"Component Product","description":"The unique identifier of the component, for example, `games`.","properties":{"name":{"description":"The component name is the name that is displayed in your storefront.","type":"string","x-go-name":"Name"},"min":{"description":"The minimum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum number of product options a shopper can select from this component.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"options":{"description":"The product options included in a component. This can be the ID of another bundle.","type":"array","items":{"type":"object","title":"Component Product Option","description":"The product options included in a component. This can be the ID of another bundle.","properties":{"id":{"description":"A unique identifier of the product you want to add to a component.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","default":"product","example":"product","enum":["product"]},"quantity":{"description":"The number of this product option that a shopper must purchase.","type":"integer","example":2,"x-go-name":"Quantity"},"min":{"description":"The minimum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Min","nullable":true},"max":{"description":"The maximum quantity of this product option that a shopper can select.","type":"integer","x-go-name":"Max","nullable":true},"sort_order":{"description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.","type":"integer","example":15,"x-go-name":"Sort Order","nullable":true},"default":{"description":"The boolean indicates whether the current option is a default option for the component.","type":"boolean","example":true,"default":false,"x-go-name":"Default","nullable":true},"product_should_be_substituted_with_child":{"description":"Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.","type":"boolean","example":true,"x-go-name":"Is Parent Product","nullable":true},"excluded_children":{"description":"Merchants can exclude specific child products from a parent product when configuring a bundle.","type":"array","items":{"type":"string"},"example":["2d491d1c-729d-43d7-a2d2-e0a56edab43d"],"x-go-name":"Excluded Children","x-omitempty":true}}},"x-go-name":"Options"}}}},"custom_inputs":{"type":"object","title":"Custom Inputs","description":"You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this using the `custom_inputs` attribute.\n\n - You can rename input to something more representative of the input that shoppers are adding, for example, `message` or `front`.\n - `name` is the name that is displayed in your storefront.\n - You can add validation rules. For example, the input field must be a string and/or up to 255 characters in length. The limit is 255 characters.\n","additionalProperties":{"type":"object","title":"Custom Input","description":"The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.","properties":{"name":{"description":"The name for the custom text field that is displayed in your storefront.","type":"string","x-go-name":"Name","example":"Message"},"validation_rules":{"description":"The validation rules for the custom text.","type":"array","x-go-name":"ValidationRules","items":{"type":"object","title":"Custom Input Validation Rule","description":"The validation rules for the custom text.","x-go-name":"CustomInputValidationRule","properties":{"type":{"description":"This represents the type of object being returned. Must be `string`.","type":"string","x-go-name":"Type","default":"string","example":"string","enum":["string"]},"options":{"type":"object","description":"The length of the custom input text field.","x-go-name":"CustomInputValidationRuleOptions","properties":{"max_length":{"description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.","type":"integer","x-go-name":"MaxLength","example":255}},"title":"custom-input-validation-rule-options"}}}},"required":{"description":"This is `true` or `false` depending on whether the custom text is required.","type":"boolean","x-go-name":"Required","example":false,"default":false,"nullable":true}}}},"sku":{"description":"The unique stock keeping unit of the product.","type":"string","example":"blue-shirt","x-go-name":"Sku"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string","example":"blue-shirt","x-go-name":"Slug"},"status":{"description":"The status of the product, either `live` or `draft`.","type":"string","example":"live","x-go-name":"Status"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example.","type":"string","x-go-name":"ExternalRef","nullable":true},"updated_at":{"description":"The date and time a product was updated.","type":"string","example":"1970-01-01T00:00:00.000","format":"date-time","x-go-name":"UpdatedAt"},"extensions":{"type":"object","title":"Extensions","description":"With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.","additionalProperties":{"type":"object","title":"Extension","description":"The name of the product template.","additionalProperties":{"description":"The product attributes available for this template.","type":"object"}}}},"x-go-name":"ProductAttributes"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","title":"ProductRelationships","description":"Relationships allow you to move between requests. Includes links to the parent and child products, bundle component products, files, and main images associated with a product.","properties":{"parent":{"description":"The details of a `parent` product. A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint.","type":"object","properties":{"data":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"}},"x-go-name":"Parent","x-omitempty":true},"children":{"description":"The details of a `child` product. When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-go-name":"Children","x-omitempty":true},"files":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"data":{"type":"array","items":{"description":"In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.","type":"object","properties":{"type":{"description":"This represents the type of object being returned. Always `file`.","type":"string","example":"file","enum":["file"]},"id":{"description":"A unique identifier for a file.","type":"string","format":"uuid"},"created_at":{"description":"The date and time a file is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","x-go-name":"CreatedAt"}},"x-go-name":"FileRelationship","title":"file-reference"}}},"x-omitempty":true,"title":"files-relationship"},"main_image":{"type":"object","description":"In Product Experience Manager, products can also have associated product images.","properties":{"data":{"description":"The images associated with a product.","type":"object","x-nullable":"true","properties":{"type":{"description":"This represents the type of object being returned. Always `main_image`.","type":"string","example":"main_image","enum":["main_image"]},"id":{"description":"A unique identifier for an image.","type":"string","format":"uuid"}}}},"x-omitempty":true,"title":"main-image-relationship"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bundle components.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string"}},"required":["self"],"title":"self-link"}},"x-omitempty":true,"title":"component-products-relationship"},"custom_relationships":{"description":"A product can have custom relationships added that link to other products. These can be used for Parent/Child relationships as well as products that you want to Cross Sell/Promote.","type":"object","properties":{"data":{"type":"array","title":"ProductReferences","description":"A list of product identifiers.","items":{"type":"object","title":"ProductReference","description":"A product identifier.","x-nullable":"true","properties":{"id":{"description":"A unique identifier for a product.","type":"string","format":"uuid","x-go-name":"ID"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","x-go-name":"Type","example":"product","enum":["product"]}},"x-go-name":"ProductReference"},"x-go-name":"ProductReferences"},"links":{"description":"For each custom relationship in use on the product, there will be a link to follow.","type":"object","title":"custom-relationship-links"}},"x-omitempty":true,"title":"custom-relationship"}},"x-go-name":"ProductRelationships","x-omitempty":true},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","title":"ProductMeta","description":"A product's metadata contains information about products, for example, the nodes a product is associated with, any child products, bundle configurations, and so on.","properties":{"bread_crumbs":{"description":"The relationship among the array of nodes a product is associated with, demonstrating the linking of the children nodes with the parent nodes. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"object","additionalProperties":{"type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"}},"x-omitempty":true},"bread_crumb_nodes":{"description":"An array of parent node IDs that a product is associated with. Up to 10 levels of parent nodes are displayed, depending on the number of levels of parent nodes you have.","type":"array","items":{"type":"string","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"x-omitempty":true},"catalog_id":{"description":"A unique identifier of the catalog a product is associated with.","type":"string","example":"362a16dc-f7c6-4280-83d6-4fcc152af091","x-go-name":"CatalogID"},"pricebook_id":{"description":"The unique identifier of the price book a product is associated with.","type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"catalog_source":{"description":"The source of a catalog. Always `pim`.","type":"string","example":"pim","enum":["pim"],"x-go-name":"CatalogSource"},"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"bundle_configuration":{"type":"object","title":"BundleConfiguration","description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","properties":{"selected_options":{"type":"object","description":"The product options included in a component. This can be the ID of another bundle.","example":{"games":{"p292e1db-c919-4d2f-984a-c2ddc79df024":2},"consoles":{"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a":1}},"additionalProperties":{"description":"The unique identifier of the component, for example, `games`.","type":"object","example":"759ce0d7-e248-4f57-8ee1-6fd81a1b3c0a","additionalProperties":{"description":"The number of this product option that a shopper must purchase.","type":"integer","format":"int64","example":1}}}},"required":["selected_options"],"x-go-name":"ProductBundleConfiguration"},"component_products":{"description":"A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.","type":"object","additionalProperties":{"type":"object","properties":{"sale_id":{"description":"With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. This is the unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"pricebook_id":{"type":"string","example":"f5466169-0037-460c-b181-b02682b6f4de","x-go-name":"PricebookID","nullable":true},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"}},"x-go-name":"ComponentProductMeta"}},"component_product_data":{"description":"This will contain the component product details (with bundle specific pricing) in the configure bundle response for the selected options.","type":"object","additionalProperties":"circular(Product)"},"price_modifiers":{"type":"object","description":"You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price.","additionalProperties":{"description":"A name for the modifier. The name must be unique and is case-sensitive.","type":"object","properties":{"modifier_type":{"description":"There are three modifier types.\n\n - The `price_increment` type increases the prices of a product.\n - The `price_decrement` type decreases the price of a product.\n - The `price_equals` type sets the price of a product to an amount you specify.\n","type":"string","example":"price_equals"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}},"x-go-name":"PriceModifierMeta"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"ProductMetaTier"},"x-go-name":"ProductMetaTiers"},"variation_matrix":{"description":"The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. If no variations are available, the `variation_matrix` is empty.","type":"object"},"variations":{"description":"If you specified `build_rules` for a product, the `variations` object lists the variation option IDs that you specified to include when building your child products. If no `build_rules` are specified, all the variation and variation options available for a product are displayed. If a product does not have any variations, then the `variations` object is not displayed.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true},"child_option_ids":{"description":"An array of variation options IDs that a child product has.","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true},"child_variations":{"description":"If this is a child product, the `child_variations` object lists the variation option IDs that define this child product.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier of a variation.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"option":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"},"options":{"description":"The options available for this variation.","type":"array","x-omitempty":true,"items":{"description":"The options available for a variation.","type":"object","properties":{"id":{"description":"A unique identifier for an option.","type":"string","format":"uuid","x-go-name":"ID"},"name":{"description":"The name of the option.","type":"string"},"sort_order":{"description":"If you specified a `sort_order` when creating your variations and variation options, then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.","type":"integer","x-go-name":"Sort Order","nullable":true},"description":{"description":"The option description to display to customers.","type":"string"}},"x-go-name":"ProductVariationOption","title":"variation_option"}}},"x-go-name":"ProductVariation","title":"variation"},"x-omitempty":true,"nullable":true},"product_types":{"description":"Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.\n\n Product types can also be used in catalogs. For example, in your catalog, you can filter on parent so that only your parent products are displayed in your storefront.\n\n Products have one of the following types:\n\n - **standard** - Standard products are a standalone products.\n - **parent** - A parent product is a product that has child products that have been built using the `Build Child Products` endpoint.\n  - **child** - When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.\n - **bundle** - A bundle is a purchasable product, comprising two or more standalone products (in other words, components) to be sold together. \n","type":"array","items":{"type":"string"},"x-omitempty":true,"x-go-name":"ProductTypes"},"language":{"description":"If you storefront supports multiple languages, your storefront's preferred language and locale.","type":"string","example":"en-GB"},"custom_relationships":{"description":"In Commerce Manager you can define Custom Relationships for Products. These allow Merchandisers to set up Cross Sell/Parent Child Relationships between products for display to shoppers.\nThis field will list the slugs(identifiers) of Custom Relationships that have been associated with this product. This will allow conditional rendering of related product sections if needed \nand provides the slug(s) needed to list the related products for the Product\n","type":"array","items":{"type":"string","example":["CRP-Cross-Sell-Products","CRP-Frequently-Bought-Together-Products"]},"x-omitempty":true,"x-go-name":"CustomRelationships"},"available_prices":{"description":"If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api","type":"array","items":{"type":"object","x-go-name":"AvailablePrice","properties":{"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sales":{"type":"object","title":"Sales","description":"A set of sale specifications","additionalProperties":{"type":"object","description":"A set of sale prices and a validity period.","properties":{"schedule":{"type":"object","description":"A definition of the times at which a sale is valid","properties":{"valid_from":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"Schedule","title":"schedule"},"currencies":{"type":"object","title":"TieredCurrencies","description":"Collection of currency specific prices for a product.","additionalProperties":{"type":"object","title":"TieredAmount","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","type":"object","additionalProperties":{"description":"The name of the tier, for example, `Pencils`.","type":"object","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":5,"x-go-name":"MinimumQuantity"},"amount":{"description":"The price for each quantity.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"}},"x-go-name":"TierAmount"},"x-go-name":"Tiers"}},"x-go-name":"TieredAmount"}}},"title":"sale"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"type":"object","title":"Tiers","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","title":"Tier","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","example":"5"},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}}}}}}},"title":"available-prices"},"alternative_prices":{"description":"If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially","type":"array","items":{"type":"object","x-go-name":"alternativePrice","properties":{"name":{"description":"A name to signify what the alternative price means to the shopper... i.e. 'List Price'","type":"string"},"pricebook_id":{"description":"A unique identifier of a price book.","type":"string"},"shopper_attributes":{"type":"object","description":"A collection of key-value string pairs, viewable by shoppers.","title":"ShopperAttributes","additionalProperties":{"type":"string"}},"sale_id":{"description":"The unique identifier of a sale.","type":"string","x-go-name":"SaleID"},"sale_expires":{"description":"The expiration date and time of the sale, provided in UTC.","type":"string","format":"date-time","example":"2025-07-07T14:30:00Z","x-go-name":"SaleExpires","nullable":true},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"tiers":{"description":"You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.","type":"object","additionalProperties":{"description":"The name of the tier, such as `Pencils`.","type":"object","properties":{"original_price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"price":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","title":"Currencies","additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","title":"Amount","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","example":100,"format":"int64","x-omitempty":false,"x-go-name":"Amount"},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"}},"x-go-name":"PriceAmount"}},"display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"},"original_display_price":{"type":"object","description":"A price formatted for display.","x-omitempty":true,"properties":{"with_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}},"without_tax":{"type":"object","title":"FormattedPrice","x-omitempty":true,"description":"A price formatted for display.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","x-omitempty":false,"example":"47500"},"currency":{"description":"The three-letter ISO code of the currencies associated with this price and the amount.","type":"string","example":"USD"},"formatted":{"description":"The format of the price for display.","type":"string","example":"$475.00"},"float_price":{"description":"The price in displayable float format","type":"number","x-omitempty":false,"example":475}}}},"title":"display-price"}},"x-go-name":"AlternativePriceTier"},"x-go-name":"AlternativePriceTiers"}}},"title":"alternative-prices"},"available_pricebook_ids":{"description":"An array of all pricebooks that have prices for this product","type":"array","items":{"type":"string","example":["8dbb35b2-ef04-477e-974d-e5f3abe6faae","6ddf2a66-d805-449c-a0e1-8e81335e31a6"]},"x-omitempty":true,"nullable":true}},"x-go-name":"ProductMeta","x-omitempty":true}},"x-go-name":"Product"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included-response"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a catalog release by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a catalog release by ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases/{release_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the specified catalog release.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The unique identifier of a published release of the catalog or `latestPublished` for the most recently published version.","name":"release_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The catalog.","content":{"application/json":{"schema":{"type":"object","title":"Release Data","description":"Container for a catalog release.","properties":{"data":{"type":"object","title":"Release","description":"A catalog release represents a collection of hierarchical product data, price books and catalogs rules.","properties":{"id":{"description":"A unique identifier for the catalog release.","type":"string","x-go-name":"ID","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a release.","type":"string","example":"Clothing"},"published_at":{"description":"The date and time a release was published.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"catalog_id":{"description":"A unique identifier for the catalog.","type":"string","example":"0194f54d-f2a1-4e33-9a6e-9ec366152490"},"description":{"description":"A description of the catalog release.","type":"string","example":"Catalog for Store 123","default":""},"hierarchies":{"description":"An array of hierarchy IDs associated with the release.","type":"array","items":{"type":"object","title":"NodeReference","description":"Minimum set of information to identify a catalog node.","properties":{"id":{"description":"The unique identifier of a hierarchy.","type":"string","example":"65477ce0-fcb8-436b-a120-3d57979421dd","x-go-name":"ID"},"label":{"description":"A label for a hierarchy.","type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Name"}},"x-go-name":"NodeReference"},"x-go-name":"RootNodes"}}},"relationships":{"type":"object","title":"ReleaseRelationships","description":"Relationships are established between different catalog entities. For example, products, hierarchies, price books, and catalog rules are related to a catalog, as they are associated with it.","properties":{"delta":{"description":"A URL to a delta document that describes the changes between catalog releases.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"products":{"description":"A URL to all products included in a catalog release.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"hierarchies":{"description":"A URL to all hierarchies included in a catalog release.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]}},"x-go-name":"ReleaseRelationships"},"type":{"description":"This represents the type of object being returned. Always `catalog-release`.","type":"string","x-go-name":"Type"},"meta":{"type":"object","title":"ReleaseMeta","description":"A release's metadata.","properties":{"created_at":{"description":"The date and time a release is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000"},"started_at":{"description":"The date and time a release is available for use. In other words, the date and time the status of a catalog release changes to PUBLISHED, rather than IN PROGRESS.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"updated_at":{"description":"The date and time a release is updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"release_status":{"description":"The status of the current release.","type":"string","enum":["PENDING","IN_PROGRESS","FAILED","PUBLISHED"]},"language":{"description":"Your storefront's preferred language code and locale.","type":"string","example":"en-GB"},"is_full_publish":{"description":"Indicates that a full publish was performed (either because this is the first time a catalog has been published or because of a change that occurred, for example, adding/removing a price book or hierarchy). When determining whether delta data needs to be refreshed, ignore this attribute and always use the `is_full_delta` attribute.\n","type":"boolean","example":false,"default":false,"x-go-name":"IsFullPublish"},"is_full_delta":{"description":"Indicates whether the release delta file contains the full content of a catalog release. Using a search service as an example, if the `is_full_delta` attribute is `true`, you should remove all data about that catalog release from the search service before injecting fresh data from the delta file. If the `is_full_delta` attribute is `false`, then data from the previous catalog release overlays the existing data in the delta file. The `is_full_delta` attribute is always `true` the first time a catalog is published.\n","type":"boolean","example":false,"default":false,"x-go-name":"IsFullDelta"},"total_products":{"description":"The total number of products displayed in a catalog release.","type":"integer","format":"int64","x-go-name":"TotalProducts","nullable":true},"total_nodes":{"description":"The total number of hierarchy nodes displayed in a catalog release.","type":"integer","format":"int64","x-go-name":"TotalNodes","nullable":true},"percent_completed":{"description":"An integer that represents the progress of a catalog publish. The attribute starts at `0` and reaches `100` when publishing is complete.","type":"integer","format":"int32","x-go-name":"PercentCompleted","nullable":true},"owner":{"description":"The owner of the resource, can be either `organization` or `store`.","type":"string","enum":["store","organization"],"x-go-name":"Owner","nullable":true},"price_segmentation_enabled":{"description":"This indicates whether the catalog release will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean"},"includes_draft_products":{"description":"When `true`, this catalog release includes `draft` products in its published data. This reflects the catalog `include_draft_products` attribute at the time of publish.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesDraftProducts"}},"x-go-name":"ReleaseMeta","x-omitempty":true}},"x-go-name":"Release"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Gets all authorized catalog releases

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Gets all authorized catalog releases"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/{catalog_id}/releases"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a list of all published releases of the specified catalog. Currently, published catalogs are limited to the current release and two releases prior to the current release. You can see the differences between the last 2 consecutive catalog releases using the `delta` link returned in the response of a `publish a catalog` endpoint.

You can use the `is_full_delta` attribute returned from the `get a release of a catalog` endpoint to determine if you need to refresh the data in your company system before publishing a catalog release and injecting fresh data in a delta link. The `is_full_delta` attribute tells you if this is a full publish of a catalog release. Using a search service as an example, if the `is_full_delta` attribute is `true`, you should remove all data about that catalog from the search service before publishing a catalog release and injecting fresh data from the delta file. 

If the `is_full_publish` attribute returned in the response is `false`, data from the previous catalog release overlaid the existing data in the delta file. The `is_full_publish` attribute is always `true` the first time a catalog is published. When determining whether delta data needs to be refreshed, ignore this attribute and always use the `is_full_delta` attribute.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","required":false,"schema":{"type":"string"}},{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of catalogs.","content":{"application/json":{"schema":{"type":"object","title":"ReleaseListData","description":"Container for a list of catalog releases.","properties":{"data":{"type":"array","items":{"type":"object","title":"Release","description":"A catalog release represents a collection of hierarchical product data, price books and catalogs rules.","properties":{"id":{"description":"A unique identifier for the catalog release.","type":"string","x-go-name":"ID","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a release.","type":"string","example":"Clothing"},"published_at":{"description":"The date and time a release was published.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"catalog_id":{"description":"A unique identifier for the catalog.","type":"string","example":"0194f54d-f2a1-4e33-9a6e-9ec366152490"},"description":{"description":"A description of the catalog release.","type":"string","example":"Catalog for Store 123","default":""},"hierarchies":{"description":"An array of hierarchy IDs associated with the release.","type":"array","items":{"type":"object","title":"NodeReference","description":"Minimum set of information to identify a catalog node.","properties":{"id":{"description":"The unique identifier of a hierarchy.","type":"string","example":"65477ce0-fcb8-436b-a120-3d57979421dd","x-go-name":"ID"},"label":{"description":"A label for a hierarchy.","type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Name"}},"x-go-name":"NodeReference"},"x-go-name":"RootNodes"}}},"relationships":{"type":"object","title":"ReleaseRelationships","description":"Relationships are established between different catalog entities. For example, products, hierarchies, price books, and catalog rules are related to a catalog, as they are associated with it.","properties":{"delta":{"description":"A URL to a delta document that describes the changes between catalog releases.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"products":{"description":"A URL to all products included in a catalog release.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"hierarchies":{"description":"A URL to all hierarchies included in a catalog release.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]}},"x-go-name":"ReleaseRelationships"},"type":{"description":"This represents the type of object being returned. Always `catalog-release`.","type":"string","x-go-name":"Type"},"meta":{"type":"object","title":"ReleaseMeta","description":"A release's metadata.","properties":{"created_at":{"description":"The date and time a release is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000"},"started_at":{"description":"The date and time a release is available for use. In other words, the date and time the status of a catalog release changes to PUBLISHED, rather than IN PROGRESS.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"updated_at":{"description":"The date and time a release is updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"release_status":{"description":"The status of the current release.","type":"string","enum":["PENDING","IN_PROGRESS","FAILED","PUBLISHED"]},"language":{"description":"Your storefront's preferred language code and locale.","type":"string","example":"en-GB"},"is_full_publish":{"description":"Indicates that a full publish was performed (either because this is the first time a catalog has been published or because of a change that occurred, for example, adding/removing a price book or hierarchy). When determining whether delta data needs to be refreshed, ignore this attribute and always use the `is_full_delta` attribute.\n","type":"boolean","example":false,"default":false,"x-go-name":"IsFullPublish"},"is_full_delta":{"description":"Indicates whether the release delta file contains the full content of a catalog release. Using a search service as an example, if the `is_full_delta` attribute is `true`, you should remove all data about that catalog release from the search service before injecting fresh data from the delta file. If the `is_full_delta` attribute is `false`, then data from the previous catalog release overlays the existing data in the delta file. The `is_full_delta` attribute is always `true` the first time a catalog is published.\n","type":"boolean","example":false,"default":false,"x-go-name":"IsFullDelta"},"total_products":{"description":"The total number of products displayed in a catalog release.","type":"integer","format":"int64","x-go-name":"TotalProducts","nullable":true},"total_nodes":{"description":"The total number of hierarchy nodes displayed in a catalog release.","type":"integer","format":"int64","x-go-name":"TotalNodes","nullable":true},"percent_completed":{"description":"An integer that represents the progress of a catalog publish. The attribute starts at `0` and reaches `100` when publishing is complete.","type":"integer","format":"int32","x-go-name":"PercentCompleted","nullable":true},"owner":{"description":"The owner of the resource, can be either `organization` or `store`.","type":"string","enum":["store","organization"],"x-go-name":"Owner","nullable":true},"price_segmentation_enabled":{"description":"This indicates whether the catalog release will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean"},"includes_draft_products":{"description":"When `true`, this catalog release includes `draft` products in its published data. This reflects the catalog `include_draft_products` attribute at the time of publish.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesDraftProducts"}},"x-go-name":"ReleaseMeta","x-omitempty":true}},"x-go-name":"Release"}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"The unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a catalog rule by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a catalog rule by ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/rules/{catalog_rule_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a catalog rule by ID

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog rule ID.","name":"catalog_rule_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The catalog rile.","content":{"application/json":{"schema":{"type":"object","title":"CatalogRuleData","description":"Container for a single catalog rule.","properties":{"data":{"type":"object","title":"Catalog Rule","description":"A catalog rule specifies which catalog to use for a given shopper context.","properties":{"id":{"type":"string","description":"The catalog rule ID. Use this to get, modify, or delete the catalog rule.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog rule. The name must not contain any spaces.","type":"string","example":"rule-123"},"description":{"description":"A brief description of the purpose of a catalog rule.","type":"string","example":"Catalog Rule for most favored customers","default":"","x-omitempty":true},"account_ids":{"description":"The list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.","type":"array","items":{"type":"string"},"x-omitempty":true},"account_tag_ids":{"description":"The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.","type":"array","items":{"type":"string"},"x-omitempty":true},"customer_ids":{"description":"The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.","type":"array","items":{"type":"string"},"x-omitempty":true},"channels":{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","type":"array","items":{"type":"string"},"x-omitempty":true},"tags":{"description":"A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","type":"array","items":{"type":"string"},"x-omitempty":true},"schedules":{"description":"Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n","type":"array","items":{"type":"object","title":"Catalog Schedule","description":"A period of time during which a catalog is valid","properties":{"valid_from":{"description":"Matches the date and time that the catalog is displayed from.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"Matches the date and time the catalog is displayed to.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"RuleSchedule"},"x-omitempty":true},"catalog_id":{"type":"string","description":"The unique identifier of a catalog.","example":"d09b4e16-08a5-4f42-817c-6e0d98acbb63"},"created_at":{"description":"The date and time a catalog rule was created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog release is updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"}},"required":["name","catalog_id","created_at","updated_at"]},"type":{"description":"This represents the type of object being returned. Always `catalog_rule`.","type":"string","example":"catalog_rule","enum":["catalog_rule"]},"meta":{"type":"object","title":"ruleMeta","description":"A rule's metadata.","properties":{"similarity_score":{"description":"Indicates the similarity score of the rule to the supplied validation request. \nThe score is calculated based on matching criteria:\n- **Name match**: 100 points (exact match)\n- **Account IDs**: 5 points per matching account\n- **Customer IDs**: 5 points per matching customer  \n- **Channels**: 5 points per matching channel\n- **Tags**: 5 points per matching tag\n- **Catalog ID**: 3 points (exact match)\n- **Pricebook IDs**: 2 points per matching pricebook\n- **Schedules**: 2 points per overlapping schedule\n\nHigher scores indicate greater similarity. Rules are sorted by similarity score in descending order.\n","type":"integer","example":100,"x-go-name":"SimilarityScore","x-omitempty":true,"nullable":true},"active":{"description":"will the rule be active at the supplied match date/time?","type":"boolean","example":false,"default":false,"x-go-name":"Active"},"resolved_for_shopper":{"description":"Indicates whether this rule will be the one resolved for a shopper viewing the catalog at the supplied match date/time","type":"boolean","example":true,"default":false},"release_id":{"type":"string","description":"The unique identifier of the published release of the catalog for the rule","x-omitempty":true,"nullable":true}},"x-go-name":"ruleMeta","x-omitempty":true}},"required":["id","type","attributes"]},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"An unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Gets all authorized catalog rules

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Gets all authorized catalog rules"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/catalogs/rules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all authorized catalog rules.

### Filtering

This endpoint supports filtering. For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering). The following operators and attributes are supported.

| Operator | Description | Supported Attributes | Example |
|:--- |:--- |:--- |:--- |
| `eq` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | `id`,`catalog_id`,`account_ids`,`customer_ids`,`channels`,`tags`,`pricebook_ids` | `filter=eq(id,some-id)` | 
| `in` | Checks if the values are included in the specified string. If they are, the condition is true. | `id`,`account_ids`,`customer_ids`,`channels`,`tags`,`pricebook_ids` | `filter=in(account_ids,some-id,another-id)` | 

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","description":"This endpoint supports filtering. See [Filtering](#filtering).\n","required":false,"schema":{"type":"string"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of catalog rules.","content":{"application/json":{"schema":{"type":"object","title":"CatalogRuleListData","description":"Container for a list of catalog rules.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Catalog Rule","description":"A catalog rule specifies which catalog to use for a given shopper context.","properties":{"id":{"type":"string","description":"The catalog rule ID. Use this to get, modify, or delete the catalog rule.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog rule. The name must not contain any spaces.","type":"string","example":"rule-123"},"description":{"description":"A brief description of the purpose of a catalog rule.","type":"string","example":"Catalog Rule for most favored customers","default":"","x-omitempty":true},"account_ids":{"description":"The list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.","type":"array","items":{"type":"string"},"x-omitempty":true},"account_tag_ids":{"description":"The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.","type":"array","items":{"type":"string"},"x-omitempty":true},"customer_ids":{"description":"The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.","type":"array","items":{"type":"string"},"x-omitempty":true},"channels":{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","type":"array","items":{"type":"string"},"x-omitempty":true},"tags":{"description":"A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","type":"array","items":{"type":"string"},"x-omitempty":true},"schedules":{"description":"Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n","type":"array","items":{"type":"object","title":"Catalog Schedule","description":"A period of time during which a catalog is valid","properties":{"valid_from":{"description":"Matches the date and time that the catalog is displayed from.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"Matches the date and time the catalog is displayed to.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"RuleSchedule"},"x-omitempty":true},"catalog_id":{"type":"string","description":"The unique identifier of a catalog.","example":"d09b4e16-08a5-4f42-817c-6e0d98acbb63"},"created_at":{"description":"The date and time a catalog rule was created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog release is updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"}},"required":["name","catalog_id","created_at","updated_at"]},"type":{"description":"This represents the type of object being returned. Always `catalog_rule`.","type":"string","example":"catalog_rule","enum":["catalog_rule"]},"meta":{"type":"object","title":"ruleMeta","description":"A rule's metadata.","properties":{"similarity_score":{"description":"Indicates the similarity score of the rule to the supplied validation request. \nThe score is calculated based on matching criteria:\n- **Name match**: 100 points (exact match)\n- **Account IDs**: 5 points per matching account\n- **Customer IDs**: 5 points per matching customer  \n- **Channels**: 5 points per matching channel\n- **Tags**: 5 points per matching tag\n- **Catalog ID**: 3 points (exact match)\n- **Pricebook IDs**: 2 points per matching pricebook\n- **Schedules**: 2 points per overlapping schedule\n\nHigher scores indicate greater similarity. Rules are sorted by similarity score in descending order.\n","type":"integer","example":100,"x-go-name":"SimilarityScore","x-omitempty":true,"nullable":true},"active":{"description":"will the rule be active at the supplied match date/time?","type":"boolean","example":false,"default":false,"x-go-name":"Active"},"resolved_for_shopper":{"description":"Indicates whether this rule will be the one resolved for a shopper viewing the catalog at the supplied match date/time","type":"boolean","example":true,"default":false},"release_id":{"type":"string","description":"The unique identifier of the published release of the catalog for the rule","x-omitempty":true,"nullable":true}},"x-go-name":"ruleMeta","x-omitempty":true}},"required":["id","type","attributes"]}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"An unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Publishes a catalog

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Publishes a catalog"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/catalogs/{catalog_id}/releases"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Publishes a catalog. You must publish a catalog before you can retrieve that catalog in an organization or store. The hierarchies, live products, and prices associated with a published catalog are in read-only mode. If you make a change to these resources, for example, a change to your price book or hierarchies, you need to republish the catalog.

You can get [a catalog release](/docs/api/pxm/catalog/get-release-by-id) to retrieve a published catalog. Currently, published catalogs are limited to the current release and two releases prior to the current release.

You can see the differences between the last 2 consecutive catalog releases. This is useful if want to understand how your products have changed in your catalog, ensuring your site search integration is kept up-to-date.

Once a catalog release has completed publishing, the delta relationship links to the delta document.

The `delta` links are signed and only valid for 1 hour. Re-reading a catalog release, for example, using [Getting a release of a catalog](/docs/api/pxm/catalog/get-release-by-id) returns a fresh a link.

You can use the `is_full_delta` attribute returned from the `get a release of a catalog` endpoint to determine if you need to refresh the data in your company system before injecting fresh data in a `delta` link. The `is_full_delta` attribute tells you if this is a full publish of the catalog. Using a search service as an example, if the `is_full_delta` attribute is `true`, you should remove all data about that catalog from the search service before injecting fresh data from the `delta` file. If the `is_full_delta` attribute is `false`, then data from the previous catalog overlays the existing data in the `delta` file. To publish a catalog and inject fresh data in a `delta` link, set `export_full_delta` to `true`.

If a previous catalog publish date is greater than 90 days, then a full catalog publish is automatically performed. If you publish your catalogs infrequently, Commerce may perform a full publish when you are expecting a delta publish.

:::caution

Generating a full delta is resource intensive and slows down the publishing process and so should only be performed in certain circumstances, for example, when initializing an integration with a service like Algolia.

:::

The `is_full_delta` attribute is always `true` the first time a catalog is published. The information is stored in a collection of `json` documents in a compressed file. You can either manually check the file or, for example, use them to automatically update another company system you may have.

- Delta files are only available for 30 days.
- Delta files are removed when a catalog release is deleted.

Each document has a `delta_type` with one of the following values, depending on whether a product has been deleted, updated or created in a catalog release.

- `delete` describes products deleted from this release of a catalog.
- `createupdate` describes products updated in this release of a catalog.

### Multi-Store Management Solutions

In a multi-store management solution.

- You can create organization catalogs. Your organization catalogs are available for your stores to use.
- Your stores can create their own catalogs.
- Your stores can create catalogs that have a combination of organization products and store products.

If you are publishing a catalog in a store that contains resources from an organization, in Commerce Manager, you must enable the **Include Organization Resources in Catalog Publishes** checkbox.

1. Go to **SYSTEM** > **Store Settings**.
2. Click **General Settings**.
3. Select **PXM** from the list.
4. Select the **Include Organization Resources in Catalog Publishes** checkbox.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"CatalogReleaseCreateData","description":"Creates a catalog release with the following attributes.","properties":{"data":{"type":"object","properties":{"export_full_delta":{"type":"boolean","description":"Set to `true` if you want to export all the data from a catalog release in a delta link. The `is_full_delta` attribute is returned from the `get a release of a catalog` endpoint. The `is_full_delta` attribute tells you if the delta file contains the full content of a catalog release. You can use the `is_full_delta` to determine if you need to refresh the data in your company system before publishing a catalog release with fresh data in a delta link. Using a search service as an example, if the `is_full_delta` attribute is true, you should remove all data about that catalog from the search service before publishing a catalog release and injecting fresh data from the delta file. If the `is_full_delta` attribute is false, then data from the previous catalog overlays the existing data in the delta file. The `is_full_delta` attribute is always `true` the first time a catalog is published.\n","x-go-name":"ExportFullDelta"},"include_organization_resources":{"type":"boolean","description":"If you are publishing a catalog in a store that contains resources from an organization, you must set this to true and you must enable the **Include Organization Resources in Catalog Publishes** checkbox in Commerce Manager. See [**Multi-Store Management Solutions**](/docs/api/pxm/catalog/publish-release).","x-go-name":"IncludeOrganizationResources","nullable":true}}}}}}},"description":"Options for catalog release publishing"}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Publishes a catalog release with the following attributes.","content":{"application/json":{"schema":{"type":"object","title":"Release Data","description":"Container for a catalog release.","properties":{"data":{"type":"object","title":"Release","description":"A catalog release represents a collection of hierarchical product data, price books and catalogs rules.","properties":{"id":{"description":"A unique identifier for the catalog release.","type":"string","x-go-name":"ID","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a release.","type":"string","example":"Clothing"},"published_at":{"description":"The date and time a release was published.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"catalog_id":{"description":"A unique identifier for the catalog.","type":"string","example":"0194f54d-f2a1-4e33-9a6e-9ec366152490"},"description":{"description":"A description of the catalog release.","type":"string","example":"Catalog for Store 123","default":""},"hierarchies":{"description":"An array of hierarchy IDs associated with the release.","type":"array","items":{"type":"object","title":"NodeReference","description":"Minimum set of information to identify a catalog node.","properties":{"id":{"description":"The unique identifier of a hierarchy.","type":"string","example":"65477ce0-fcb8-436b-a120-3d57979421dd","x-go-name":"ID"},"label":{"description":"A label for a hierarchy.","type":"string","example":"category","x-go-name":"Label"},"name":{"description":"The name of a hierarchy.","type":"string","example":"Formal dresswear","x-go-name":"Name"}},"x-go-name":"NodeReference"},"x-go-name":"RootNodes"}}},"relationships":{"type":"object","title":"ReleaseRelationships","description":"Relationships are established between different catalog entities. For example, products, hierarchies, price books, and catalog rules are related to a catalog, as they are associated with it.","properties":{"delta":{"description":"A URL to a delta document that describes the changes between catalog releases.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"products":{"description":"A URL to all products included in a catalog release.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"hierarchies":{"description":"A URL to all hierarchies included in a catalog release.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}},"required":["links"]}},"x-go-name":"ReleaseRelationships"},"type":{"description":"This represents the type of object being returned. Always `catalog-release`.","type":"string","x-go-name":"Type"},"meta":{"type":"object","title":"ReleaseMeta","description":"A release's metadata.","properties":{"created_at":{"description":"The date and time a release is created.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000"},"started_at":{"description":"The date and time a release is available for use. In other words, the date and time the status of a catalog release changes to PUBLISHED, rather than IN PROGRESS.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"updated_at":{"description":"The date and time a release is updated.","type":"string","format":"date-time","example":"1970-01-01T00:00:00.000","nullable":true},"release_status":{"description":"The status of the current release.","type":"string","enum":["PENDING","IN_PROGRESS","FAILED","PUBLISHED"]},"language":{"description":"Your storefront's preferred language code and locale.","type":"string","example":"en-GB"},"is_full_publish":{"description":"Indicates that a full publish was performed (either because this is the first time a catalog has been published or because of a change that occurred, for example, adding/removing a price book or hierarchy). When determining whether delta data needs to be refreshed, ignore this attribute and always use the `is_full_delta` attribute.\n","type":"boolean","example":false,"default":false,"x-go-name":"IsFullPublish"},"is_full_delta":{"description":"Indicates whether the release delta file contains the full content of a catalog release. Using a search service as an example, if the `is_full_delta` attribute is `true`, you should remove all data about that catalog release from the search service before injecting fresh data from the delta file. If the `is_full_delta` attribute is `false`, then data from the previous catalog release overlays the existing data in the delta file. The `is_full_delta` attribute is always `true` the first time a catalog is published.\n","type":"boolean","example":false,"default":false,"x-go-name":"IsFullDelta"},"total_products":{"description":"The total number of products displayed in a catalog release.","type":"integer","format":"int64","x-go-name":"TotalProducts","nullable":true},"total_nodes":{"description":"The total number of hierarchy nodes displayed in a catalog release.","type":"integer","format":"int64","x-go-name":"TotalNodes","nullable":true},"percent_completed":{"description":"An integer that represents the progress of a catalog publish. The attribute starts at `0` and reaches `100` when publishing is complete.","type":"integer","format":"int32","x-go-name":"PercentCompleted","nullable":true},"owner":{"description":"The owner of the resource, can be either `organization` or `store`.","type":"string","enum":["store","organization"],"x-go-name":"Owner","nullable":true},"price_segmentation_enabled":{"description":"This indicates whether the catalog release will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean"},"includes_draft_products":{"description":"When `true`, this catalog release includes `draft` products in its published data. This reflects the catalog `include_draft_products` attribute at the time of publish.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesDraftProducts"}},"x-go-name":"ReleaseMeta","x-omitempty":true}},"x-go-name":"Release"},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}}}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Releases

When a catalog is published, a catalog release is created. A catalog release provides a snapshot of the product information taken at the time of publication. You can have one or more catalog releases available in your organization or in your store. If you publish a catalog for your organization, the catalog is available when the store is launched.

If you have more than one catalog published for your store, use catalog rules to specify when to display each catalog. For example, you can use [**catalog rules**](/docs/api/pxm/catalog/rules) to schedule a catalog to appear during a particular date and time, such as a seasonal catalog. The catalog may have different pricing than the other catalogs.

When a catalog is ready to be used in a store, you publish it. You can create and publish catalogs for different contexts and channels.

Here are some pointers to understand a catalogs' lifecycle.

- The default catalog is always the oldest published catalog and must have have at least one release.
- At any time, the most recent three catalog releases are maintained. Hence, if there is a fourth catalog release, the first catalog release is automatically removed.
- Until the catalog is published again, the previously created three catalog releases stay permanently.
- If you want any other catalog to become the default catalog, you must create a catalog rule.
- If you want the oldest published catalog to become the default catalog, you must remove the catalog rule.
- Use the `sort_order` value in the `variations` to program your storefront to display the variation options in the order that you want.

Here is a diagram that describes a catalogs' lifecycle:

![Catalogs' Lifecycle](/assets/catalog-lifecycle.png)

### Publishing catalogs

When you publish a catalog, the `live` products in the hierarchies appear in a catalog release. A catalog release provides a snapshot of product information taken at the time of publication. You can have one or more catalog releases available in your organization or in your store. If you publish a catalog for your organization, the catalog is available when the store is launched.

If you have more than one catalog published for your store, use catalog rules to specify when to display each catalog. For example, you can use [catalog rules](/docs/api/pxm/catalog/rules) to schedule a catalog to appear during a particular date and time, such as a seasonal catalog. The catalog may have different pricing than the other catalogs. You can have multiple published catalogs.

When a catalog is ready to be used in a store, you publish it. You can create and publish catalogs for different contexts and channels. You can see the differences between the last two consecutive catalog releases. See [Publish a catalog](/docs/api/pxm/catalog/publish-release).

You retrieve catalogs for your shopper experience by using the [Catalog View API](/docs/api/pxm/catalog/releases).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Rules

If your store requires multiple catalogs, add catalog rules to control when a catalog is displayed. A catalog rule contains a catalog plus the criteria under which to display the catalog.

:::caution

You cannot create catalog rules for organization catalogs.

:::

You can use catalog rules to schedule a catalog to appear during a particular period, such as on a specific date or during summer. The catalog might offer different pricing during this period. The pricing depends on the associated price book.

The following scenarios provides a few examples for using catalog rules.

- **Multiple geographical regions**. Display different catalogs in different regions with suitable pricing or combine product hierarchies from two different regions to display in a third region.
- **Multiple channels**. Display different catalogs based on how a shopper accesses your store, such as through a mobile app or a web storefront.
- **Direct to business versus direct to customers**. Offer different products and prices for business customers versus retail customers.
- **Preferred accounts**. Offer special pricing to a group of users while displaying a standard price catalog to other users.
- **Preferred customers**. Offer special pricing to preferred customers while displaying a standard price catalog to all other shoppers.
- **Reward programs**. Enable reward programs where catalog prices drop after a certain spending level is reached.
- **Product sales**. Offer sale items for a limited time.
- **Standard pricing**. Display a default catalog to the shoppers who do not meet the criteria of the other catalog rules.

You can define a catalog rule with any of the following criteria.

- **Accounts**. List the accounts that should see a catalog. When a user has logged in with the account, they see the configured catalog.
- **Customers**. List the customers that should see a catalog. When the customer is logged in, they see the configured catalog.
- **Channel**. Specify a shopper experience, such as web storefront or mobile app. Set up the channel to retrieve the catalog from the catalog rule that matches that channel.
- **Other tags**. Create your own user-defined tags. For example, you might want to tag by regions or you might want to distinguish between business and consumer customers.

If a catalog rule has no criteria defined, it is the default catalog rule.

### Resolving catalog rules

When there is a request for a catalog, the store displays the catalog with the rule that matches the most attributes of the shoppers context.

The request triggers the following steps:

1. Compares the shoppers context against the defined catalog rules.
1. Determines the best match.
1. Retrieves the catalog associated with the matching catalog rule.

The follow examples show how the best match might be resolved:

- A shopper matches one of the `customer_ids` in one catalog rule only. The catalog for that catalog rule is displayed.
- A shopper matches one of the `customer_ids` in one catalog rule only, but doesnʼt match any of the `tags` specified in that catalog rule. Because there are no other catalog rules for this `customer_id`, the catalog for the catalog rule is displayed because it is the best match.
- A shopper is browsing a store using the stores mobile app, which matches `channel=mobile` in two catalog rules. The catalog displayed depends on matches with the `tags` or `customer_ids` attributes. If there is no other matching attribute, the first catalog rule found by the store is used. The best practice is to create catalog rules that cover all cases so that you avoid this situation.
- An unknown shopper is browsing the only channel offered by the seller. The store displays the base catalog.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Shopper Catalog API

Use the Shopper Catalog View API to retrieve hierarchy, node and product information for a catalog release. When you publish a catalog for a store, you can define catalog rules so that you can show catalogs with different pricing or different products to preferred customers or channels. These endpoints can be used in your customer-facing frontends.

A catalog is a combination of one or more hierarchies, products, and a price book. Use the Products API and Hierarchies API to create a hierarchy of products that can be included in a catalog. Use the Price Book API to associate prices with products.

### Characteristics of Shopper Catalogs

Shopper catalogs can have the following characteristics.

- Use catalog rules to schedule a catalog to appear during a particular date and time, such as a seasonal catalog. The catalog may have different pricing than the other catalogs. You can have multiple published catalogs.
- If you have defined catalog rules and you want to retrieve a published catalog for a particular channel or a user-defined tag, you must set the appropriate headers in the request:
  - `EP-Channel` - The channel, such as website or mobile app. See [**Create a Catalog Rule**](/docs/api/pxm/catalog/create-rule).
  - `EP-Context-Tag` - A tag defined in the store, such as `clearance`. See [**Create a Catalog Rule**](/docs/api/pxm/catalog/create-rule).
* When a catalog is ready to be used in a store, you publish it. See [**Publish a Catalog**](/docs/api/pxm/catalog/publish-release).
* You can create and publish catalogs for different contexts and channels. You can see the differences between the last 2 consecutive catalog releases. See [**Publish a Catalog**](/docs/api/pxm/catalog/publish-release).
* You retrieve catalogs for your shopper experience by using the Shopper Catalog View API. For more information on how you can retrieve a catalog as a shopper using the Catalog API.
* When a catalog is published for a store, the corresponding events contain `store_id` and `org_id`. 
* When a catalog is published for an organization, the corresponding events contain `org_id`. 
* Use the `sort_order` value in `variations` to program your storefront to display the variation options in the order that you want.

### Shopper Catalog Caching

When conducting a `GET` on `catalog` endpoints, all data returned, including catalog releases, products, nodes and hierarchies, are cached for 5 minutes. This means, if you call the same endpoint again, the catalog data is retrieved from the cached objects pool, optimizing the performance and efficiency of your store front.

If you use any of the `catalog` endpoints with a `filter` or `include` query parameter, these are cached separately. 

The cached entries disappear from the cached objects pool after 5 minutes.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Updates a catalog

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Updates a catalog"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/catalogs/{catalog_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the catalog is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog ID.","name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"CatalogUpdateData","description":"A catalog combines price books, product lists, and hierarchies.","properties":{"data":{"type":"object","properties":{"attributes":{"type":"object","properties":{"name":{"description":"The name of the catalog.","type":"string","minLength":1,"example":"catalog-123","nullable":true},"description":{"description":"A brief description of the catalog.","type":"string","example":"Catalog for Store 123","nullable":true},"hierarchy_ids":{"description":"The unique identifiers of the hierarchies to associate with a catalog.","type":"array","items":{"type":"string"},"nullable":true},"pricebook_id":{"description":"The unique identifier of a price book to associate with a catalog. You can specify a `pricebook_id` or a `pricebook_ids` but not both. If you specify both, a `422 unprocessable entity` error is displayed.","type":"string","nullable":true},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.loc.gov/standards/iso639-2/) that represents the name of language you have used.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.loc.gov/standards/iso639-2/) that represents the name of language you have used.","type":"string"}}},"enable_price_segmentation":{"description":"This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean","example":true,"default":false,"x-go-name":"EnablePriceSegmentation"},"include_draft_products":{"description":"When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).","type":"boolean","example":false,"default":false,"x-go-name":"IncludeDraftProducts"}}},"id":{"description":"The unique identifier of the catalog to be updated.","type":"string","x-go-name":"ID","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"type":{"description":"This represents the type of object being returned. Always `catalog`.","type":"string","example":"catalog","enum":["catalog"]}},"required":["type","id","attributes"]}},"required":["data"]}}},"description":"Updated catalog.","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"An updated catalog with the following attributes.","content":{"application/json":{"schema":{"type":"object","title":"CatalogData","description":"Container for a single catalog.","properties":{"data":{"type":"object","title":"Catalog","description":"Creates a catalog with the following attributes.","properties":{"id":{"type":"string","description":"A unique identifier of a catalog.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog.","type":"string","example":"catalog-123"},"description":{"description":"A brief description of the catalog, such as the purpose of the catalog.","type":"string","example":"Catalog for Store 123","default":""},"hierarchy_ids":{"description":"The unique identifiers of the hierarchies associated with a catalog.","type":"array","items":{"type":"string"}},"pricebook_id":{"description":"The unique identifier of a price book associated with a catalog. If no price book is selected, the catalog is displayed without prices.","type":"string"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"string"}}},"created_at":{"description":"The date and time a catalog is created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog was updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"owner":{"description":"The owner of this resource, can be either `organization` or `store`.","type":"string","enum":["store","organization"],"x-go-name":"Owner","default":"store","nullable":true},"enable_price_segmentation":{"description":"This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing","type":"boolean","example":true,"default":false,"x-go-name":"EnablePriceSegmentation"},"include_draft_products":{"description":"When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).","type":"boolean","example":false,"default":false,"x-go-name":"IncludeDraftProducts"}},"required":["name","hierarchy_ids","created_at","updated_at"]},"relationships":{"description":"Relationships are established between different catalog entities. For example, a catalog rule and a price book are related to a catalog, as both are associated with it.","type":"object","title":"CatalogRelationships","properties":{"rules":{"description":"The catalog rules related to a catalog.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"}}},"releases":{"description":"When a catalog is published, a catalog release is created. This is a URL to all catalog published releases available for this catalog.","type":"object","properties":{"links":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"object","properties":{"related":{"description":"A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.","type":"string"}},"required":["related"],"title":"related-link"},"meta":{"type":"object","properties":{"count":{"description":"The number releases available for a catalog.","type":"integer"}}}}}}},"type":{"type":"string","example":"catalog","enum":["catalog"]}},"required":["id","type","attributes"]},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Updates a catalog rule

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Updates a catalog rule"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/catalogs/rules/{catalog_rule_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the catalog rule is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The catalog rule ID.","name":"catalog_rule_id","in":"path","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"CatalogRuleUpdateData","description":"A catalog rule specifies which catalog to use for a given shopper context.","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The catalog rule ID. Use this to get, modify, or delete the catalog rule.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog rule. The name must not contain spaces.","type":"string","minLength":1,"example":"rule-123","nullable":true},"description":{"description":"A description of the purpose of a catalog rule.","type":"string","example":"Catalog Rule for most favored customers","default":"","nullable":true},"account_ids":{"description":"Specifies the list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.","type":"array","items":{"type":"string"},"nullable":true},"account_tag_ids":{"description":"The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.","type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"description":"The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.","type":"array","items":{"type":"string"},"nullable":true},"channels":{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","type":"array","items":{"type":"string"},"nullable":true},"schedules":{"description":"Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n","type":"array","items":{"type":"object","title":"Catalog Schedule","description":"A period of time during which a catalog is valid","properties":{"valid_from":{"description":"Matches the date and time that the catalog is displayed from.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"Matches the date and time the catalog is displayed to.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"RuleSchedule"},"nullable":true},"tags":{"description":"A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","type":"array","items":{"type":"string"},"nullable":true},"catalog_id":{"type":"string","description":"The unique identifier of a catalog rule.","example":"d09b4e16-08a5-4f42-817c-6e0d98acbb63","nullable":true},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"}}},"type":{"description":"This represents the type of object being returned. Always `catalog_rule`.","type":"string","example":"catalog_rule","enum":["catalog_rule"]}},"required":["id","type"]}},"required":["data"]}}},"description":"An updated catalog rule with the following attributes.","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"An Updated catalog rule with the following attributes.","content":{"application/json":{"schema":{"type":"object","title":"CatalogRuleData","description":"Container for a single catalog rule.","properties":{"data":{"type":"object","title":"Catalog Rule","description":"A catalog rule specifies which catalog to use for a given shopper context.","properties":{"id":{"type":"string","description":"The catalog rule ID. Use this to get, modify, or delete the catalog rule.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog rule. The name must not contain any spaces.","type":"string","example":"rule-123"},"description":{"description":"A brief description of the purpose of a catalog rule.","type":"string","example":"Catalog Rule for most favored customers","default":"","x-omitempty":true},"account_ids":{"description":"The list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.","type":"array","items":{"type":"string"},"x-omitempty":true},"account_tag_ids":{"description":"The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.","type":"array","items":{"type":"string"},"x-omitempty":true},"customer_ids":{"description":"The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.","type":"array","items":{"type":"string"},"x-omitempty":true},"channels":{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","type":"array","items":{"type":"string"},"x-omitempty":true},"tags":{"description":"A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","type":"array","items":{"type":"string"},"x-omitempty":true},"schedules":{"description":"Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n","type":"array","items":{"type":"object","title":"Catalog Schedule","description":"A period of time during which a catalog is valid","properties":{"valid_from":{"description":"Matches the date and time that the catalog is displayed from.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"Matches the date and time the catalog is displayed to.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"RuleSchedule"},"x-omitempty":true},"catalog_id":{"type":"string","description":"The unique identifier of a catalog.","example":"d09b4e16-08a5-4f42-817c-6e0d98acbb63"},"created_at":{"description":"The date and time a catalog rule was created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog release is updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"}},"required":["name","catalog_id","created_at","updated_at"]},"type":{"description":"This represents the type of object being returned. Always `catalog_rule`.","type":"string","example":"catalog_rule","enum":["catalog_rule"]},"meta":{"type":"object","title":"ruleMeta","description":"A rule's metadata.","properties":{"similarity_score":{"description":"Indicates the similarity score of the rule to the supplied validation request. \nThe score is calculated based on matching criteria:\n- **Name match**: 100 points (exact match)\n- **Account IDs**: 5 points per matching account\n- **Customer IDs**: 5 points per matching customer  \n- **Channels**: 5 points per matching channel\n- **Tags**: 5 points per matching tag\n- **Catalog ID**: 3 points (exact match)\n- **Pricebook IDs**: 2 points per matching pricebook\n- **Schedules**: 2 points per overlapping schedule\n\nHigher scores indicate greater similarity. Rules are sorted by similarity score in descending order.\n","type":"integer","example":100,"x-go-name":"SimilarityScore","x-omitempty":true,"nullable":true},"active":{"description":"will the rule be active at the supplied match date/time?","type":"boolean","example":false,"default":false,"x-go-name":"Active"},"resolved_for_shopper":{"description":"Indicates whether this rule will be the one resolved for a shopper viewing the catalog at the supplied match date/time","type":"boolean","example":true,"default":false},"release_id":{"type":"string","description":"The unique identifier of the published release of the catalog for the rule","x-omitempty":true,"nullable":true}},"x-go-name":"ruleMeta","x-omitempty":true}},"required":["id","type","attributes"]},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Validate catalog rules for a given context

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Validate catalog rules for a given context"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/catalogs/rules/validate"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Validates catalog rules for a given context and returns a list of matching catalog rules.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/api/settings/settings-introduction#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. You would normally increment the page offset by multiples of the page limit to paginate through the results.","name":"page[offset]","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["match_type"],"properties":{"match_type":{"type":"string","enum":["filter","similarity","conflict","resolve_for_shopper"],"description":"The type of matching operation to perform on catalog rules:\n\n- **filter**: Advanced rule filtering with AND logic. Returns rules that match ALL specified criteria.\n\n- **similarity**: Finds rules similar to the supplied rule using OR logic. Returns rules sorted by similarity score (highest first) with metadata indicating:\n  - Similarity score based on matching criteria (name: 100pts, account/customer/channel/tags: 5pts each, catalog: 3pts, pricebooks: 2pts, schedules: 2pts)  \n  - Whether the rule is active at the supplied match_date\n  - Whether the rule would be resolved for a shopper context\n\n- **conflict**: Checks for conflicts between the supplied rule and existing rules. Returns rules that would conflict if the new rule were created.\n\n- **resolve_for_shopper**: Determines the exact catalog rule that would be applied for a given shopper context. Returns the single most specific matching rule or defaults to \"Default Catalog Resolution\".\n"},"channels":{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","type":"array","items":{"type":"string"},"nullable":true},"tags":{"description":"A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","type":"array","items":{"type":"string"},"nullable":true},"account_ids":{"type":"array","items":{"type":"string"},"description":"List of account IDs.","nullable":true},"account_tag_ids":{"type":"array","items":{"type":"string"},"description":"List of account tag UUIDs.","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"description":"List of customer IDs.","nullable":true},"pricebook_ids":{"type":"array","items":{"type":"string"},"description":"List of pricebook IDs.","nullable":true},"schedules":{"type":"array","items":{"type":"object","properties":{"valid_from":{"type":"string","format":"date-time"},"valid_to":{"type":"string","format":"date-time"}}},"nullable":true},"name":{"type":"string","description":"The name of the catalog rule.","nullable":true},"catalog_id":{"type":"string","description":"The id of the catalog to match against.","nullable":true},"match_date":{"type":"string","format":"date-time","description":"The date to match against the schedules.","nullable":true}}}},"title":"catalog-rule-validator-request"}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List of matching catalog rules","content":{"application/json":{"schema":{"type":"object","title":"CatalogRuleListData","description":"Container for a list of catalog rules.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"description":"Total number of results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","format":"int64"}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","format":"int64"},"offset":{"description":"The current offset by number of pages.","type":"integer","format":"int64"},"current":{"description":"The current number of pages.","type":"integer","format":"int64"},"total":{"description":"The total number of records for the entire collection.","type":"integer","format":"int64"}}}}},"data":{"type":"array","items":{"type":"object","title":"Catalog Rule","description":"A catalog rule specifies which catalog to use for a given shopper context.","properties":{"id":{"type":"string","description":"The catalog rule ID. Use this to get, modify, or delete the catalog rule.","example":"8dbb35b2-ef04-477e-974d-e5f3abe6faae"},"attributes":{"type":"object","properties":{"name":{"description":"The name of a catalog rule. The name must not contain any spaces.","type":"string","example":"rule-123"},"description":{"description":"A brief description of the purpose of a catalog rule.","type":"string","example":"Catalog Rule for most favored customers","default":"","x-omitempty":true},"account_ids":{"description":"The list of accounts who are eligible to see this catalog. If this field is empty, the rule matches all accounts.","type":"array","items":{"type":"string"},"x-omitempty":true},"account_tag_ids":{"description":"The list of account tag UUIDs. Accounts must have at least one of these tags to see this catalog. If this field is empty, the rule matches all accounts regardless of tags.","type":"array","items":{"type":"string"},"x-omitempty":true},"customer_ids":{"description":"The list of customers who are eligible to see this catalog. If empty, the rule matches all customers.","type":"array","items":{"type":"string"},"x-omitempty":true},"channels":{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","type":"array","items":{"type":"string"},"x-omitempty":true},"tags":{"description":"A list of user-defined tags that can be used to further restrict the eligibility criteria for this rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","type":"array","items":{"type":"string"},"x-omitempty":true},"schedules":{"description":"Specifies a time period when a catalog is displayed, such as on a specific date or during summer. Requests populate the rule tag using the `EP-Context-Tag` header. \n\nThe schedules attribute must include the following.\n\n- `valid_from` matches the date and time that the catalog is displayed from. \n- `valid_to` matches the date and time the catalog is displayed to. \n\nCommerce runs on UTC time. \n\nYou can offset the timezone by adding the offset to the end of the date and time. For example, a catalog which contains a sale hierarchy that should appear for a set timeframe may be scheduled to publish on a given date and time within a given timezone. For instance, a sale that should begin on 1st of June 2022 05:00 ET and end on the 15th of June 2022 at 23:50 PT would have a valid schedule of `\"valid_from\": \"2022-06-01T05:00:00.000-05:00\"`, `\"valid_to\": \"2022-06-15T11:59:99.000-08:00\"`.\n","type":"array","items":{"type":"object","title":"Catalog Schedule","description":"A period of time during which a catalog is valid","properties":{"valid_from":{"description":"Matches the date and time that the catalog is displayed from.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"Matches the date and time the catalog is displayed to.","type":"string","example":"2020-09-22T09:00:00","format":"date-time","x-go-name":"ValidTo","nullable":true}},"x-go-name":"RuleSchedule"},"x-omitempty":true},"catalog_id":{"type":"string","description":"The unique identifier of a catalog.","example":"d09b4e16-08a5-4f42-817c-6e0d98acbb63"},"created_at":{"description":"The date and time a catalog rule was created.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"updated_at":{"description":"The date and time a catalog release is updated.","type":"string","example":"2020-09-22T09:00:00","format":"date-time"},"pricebook_ids":{"description":"If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books.","type":"array","maxItems":5,"items":{"type":"object","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","format":"uuid"},"priority":{"description":"Priority is a number and the price book with the highest number has the highest priority.","type":"integer"}},"required":["priority","id"],"x-go-name":"PrioritizedPricebook"},"title":"prioritized-pricebooks"}},"required":["name","catalog_id","created_at","updated_at"]},"type":{"description":"This represents the type of object being returned. Always `catalog_rule`.","type":"string","example":"catalog_rule","enum":["catalog_rule"]},"meta":{"type":"object","title":"ruleMeta","description":"A rule's metadata.","properties":{"similarity_score":{"description":"Indicates the similarity score of the rule to the supplied validation request. \nThe score is calculated based on matching criteria:\n- **Name match**: 100 points (exact match)\n- **Account IDs**: 5 points per matching account\n- **Customer IDs**: 5 points per matching customer  \n- **Channels**: 5 points per matching channel\n- **Tags**: 5 points per matching tag\n- **Catalog ID**: 3 points (exact match)\n- **Pricebook IDs**: 2 points per matching pricebook\n- **Schedules**: 2 points per overlapping schedule\n\nHigher scores indicate greater similarity. Rules are sorted by similarity score in descending order.\n","type":"integer","example":100,"x-go-name":"SimilarityScore","x-omitempty":true,"nullable":true},"active":{"description":"will the rule be active at the supplied match date/time?","type":"boolean","example":false,"default":false,"x-go-name":"Active"},"resolved_for_shopper":{"description":"Indicates whether this rule will be the one resolved for a shopper viewing the catalog at the supplied match date/time","type":"boolean","example":true,"default":false},"release_id":{"type":"string","description":"The unique identifier of the published release of the catalog for the rule","x-omitempty":true,"nullable":true}},"x-go-name":"ruleMeta","x-omitempty":true}},"required":["id","type","attributes"]}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a `self` parameter with a link the specific resource.","type":"string","format":"uri","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links"}},"required":["data"]}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"ErrorResponse is a json-api style Error response.","properties":{"errors":{"type":"array","items":{"type":"object","title":"APIError","description":"APIError is a json-api style part of an error response.","properties":{"detail":{"type":"string","example":"not processable","x-go-name":"Detail"},"status":{"type":"string","example":"422","x-go-name":"Status"},"title":{"type":"string","example":"There was a problem processing your request.","x-go-name":"Title"}},"x-go-name":"APIError"},"x-go-name":"Errors"}},"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Catalog Search Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/catalog-search/openapi.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Catalog Search Introduction"}
>
</Heading>

Elastic Path Catalog Search provides fast, relevant product search capabilities for your published catalogs. Catalog Search enables shoppers to find products quickly using full-text search, filtering, faceting, and sorting, while giving merchandisers powerful tools to customize search relevance and ranking.

You can integrate Catalog Search into your storefront using the Catalog Search API or manage search settings through Commerce Manager.

### How Catalog Search Works

Catalog Search works alongside your Product Experience Manager catalogs to provide optimized search functionality.

When creating or updating a catalog, enable search to allow the catalog's products to be indexed. See [Catalogs](/docs/api/pxm/catalog/catalogs). Then when a search-enabled catalog is published, the products are automatically indexed for search. The search index contains product data optimized for fast querying.

Use the Search API to query products with full-text search, filtering, faceting, and sorting. The results of the search contain the full product information, not just the indexed fields, reducing the need for further API calls.

### Key Capabilities

- **Full-text search**: Search across product names, descriptions, SKUs, and custom fields with typo tolerance and relevance ranking
- **Filtering**: Narrow results using conditions on product attributes, categories, prices, and custom fields
- **Faceting**: Get aggregated counts for attribute values to build dynamic navigation and refinement options
- **Sorting**: Order results by price, name, custom fields, or relevance score
- **Search Profiles**: Configure search behavior including field weights, filters, and boost rules without code changes
- **Custom Fields**: Extend the search schema with your own product attributes for filtering, faceting, and sorting
- **Fully Hydrated Responses**: Search results contain complete information about the products, reducing the requirement for follow-up API calls.

### Personalized Search Results

Search results are automatically personalized based on the shopper's context. The system determines which catalog and prices to show based on:

- **Channel**: The shopping experience, such as a web storefront or mobile app
- **Account**: For B2B scenarios, the shopper's account and any parent accounts
- **Customer**: The logged-in customer's segment or tier
- **Tags**: Custom context tags for advanced segmentation scenarios

See [**Characteristics of Shopper Catalogs**](/docs/api/pxm/catalog/shopper-catalog-api#characteristics-of-shopper-catalogs) for more information.

### Search Profiles

Search Profiles give merchandisers control over search behavior without requiring code changes. With Search Profiles, you can:

- **Configure field weights**: Control which product fields are most important for relevance ranking
- **Apply default filters**: Enforce business rules like only showing live products
- **Boost products**: Promote featured products, specific brands, or categories to the top of results
- **A/B test**: Create multiple profiles to test different search configurations

See [**Search Profiles**](/docs/api/pxm/catalog-search/search-profiles) for more information.

### Extending the Search Schema

By default, the search index includes standard product fields like name, description, SKU, and categories. You can extend the schema by adding custom fields using [Indexable Fields](/docs/api/pxm/catalog-search/indexable-fields).

Two types of custom fields can be indexed:

- **Product extension fields** (`extensions.products(<slug>).<field>`): Fields from your product extension templates.
- **Product custom attributes** (`shopper_attributes.<attribute>` and `admin_attributes.<attribute>`): Merchant-defined key/value attributes on products.

This allows you to:

- Search on custom product attributes like brand, material, or specifications
- Filter products by custom fields like color, size, or rating
- Display facets for custom field values in your navigation
- Sort results by custom numeric fields like rating or popularity

See [**Indexable Fields**](/docs/api/pxm/catalog-search/indexable-fields) for more information.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"BearerToken"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Create indexable fields

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create indexable fields"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/catalogs/indexable-fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify additional fields to be indexed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"Represents the type of object being returned. Always `catalog_search_indexable_fields`.","type":"string","example":"catalog_search_indexable_fields","enum":["catalog_search_indexable_fields"],"title":"IndexableFieldsType"},"attributes":{"type":"object","properties":{"fields":{"type":"array","description":"A collection of indexable fields","title":"IndexableFields","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the field to index. Two formats are supported:\n\n- **Extension fields**: `extensions.products(<template_slug>).<field_name>` — indexes a field from a product extension template. The field must exist and be enabled in the flows service.\n- **Shopper attribute fields**: `shopper_attributes.<attribute_name>` — indexes a merchant-defined shopper attribute. Always typed as `string`. The attribute name must be no longer than **64 characters** and can only contain alphanumeric characters, underscores (`_`), and hyphens (`-`).\n- **Admin attribute fields**: `admin_attributes.<attribute_name>` — indexes a merchant-defined admin attribute. Always typed as `string`. The attribute name must be no longer than **64 characters** and can only contain alphanumeric characters, underscores (`_`), and hyphens (`-`).\n","example":"extensions.products(clothing).color","minLength":1},"facetable":{"type":"boolean","description":"Enables faceting on the field.","default":false,"example":true},"sortable":{"type":"boolean","description":"When set to true, the field will be sortable. Default: true for numbers, false otherwise.","example":true},"locale":{"type":"string","description":"For configuring language specific tokenization, e.g. jp for Japanese. Default: en which also broadly supports most European languages. For valid values, see [ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).","default":"en","example":"en"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting. Each element must be a single character.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide per-field special characters to index for this field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting. Each element must be a single character.\n"}},"title":"IndexableFieldRequest"},"example":[{"name":"extensions.products(clothing).color","facetable":false,"sortable":false,"locale":"en"},{"name":"shopper_attributes.fabric","facetable":false,"sortable":false},{"name":"admin_attributes.internal_grade","sortable":true}]},"core_field_overrides":{"type":"array","description":"Per-field configuration for core product fields (e.g. name, description).","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the core field to configure. Must be one of the supported core fields.\n","example":"name"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this core field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting. Each element must be a single character.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide per-field special characters to index for this core field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting. Each element must be a single character.\n"},"sortable":{"type":"boolean","description":"When set to true, enables sorting on this core field. Only supported for specific core fields.\n","example":true},"facetable":{"type":"boolean","description":"When set to true, enables faceting on this core field. A re-index is required for the change to take effect.\n","example":true}},"title":"CoreFieldOverride"}},"token_separators":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters to use as token separators across all the index fields, in addition to spaces and newlines. Each element must be a single character. Defaults to none set.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide list of special characters that should be indexed as part of the tokens across the all index fields. Each element must be a single character. Defaults to none set.\n"}},"title":"IndexableFieldsRequestAttributes"}}}},"title":"IndexableFieldsCreateRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully created indexable fields","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier of the indexable fields.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_indexable_fields`.","type":"string","example":"catalog_search_indexable_fields","enum":["catalog_search_indexable_fields"],"title":"IndexableFieldsType"},"attributes":{"type":"object","properties":{"fields":{"type":"array","x-go-type-skip-optional-pointer":true,"description":"A collection of indexable fields","title":"IndexableFields","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","description":"The name of the field.","example":"extensions.products(clothing).color","minLength":1},"type":{"type":"string","description":"The type of the field.","enum":["string","int32","int64","bool","float"],"example":"string","x-go-type":"model.FieldType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"},"title":"FieldType"},"facetable":{"type":"boolean","description":"Enables faceting on the field.","default":false,"example":true},"sortable":{"type":"boolean","description":"When set to true, the field will be sortable. Default: true for numbers, false otherwise.","example":true},"locale":{"type":"string","description":"For configuring language specific tokenization, e.g. jp for Japanese. Default: en which also broadly supports most European languages. For valid values, see [ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).","default":"en","example":"en"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Provide per-field special characters to index for this field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting.\n"}},"title":"IndexableField"},"example":[{"name":"extensions.products(clothing).color","type":"string","facetable":false,"sortable":false,"locale":"en"},{"name":"shopper_attributes.fabric","type":"string","facetable":false,"sortable":false},{"name":"admin_attributes.internal_grade","type":"string","sortable":true}]},"core_field_overrides":{"type":"array","x-go-type-skip-optional-pointer":true,"description":"Per-field configuration for core product fields (e.g. name, description).","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the core field to configure. Must be one of the supported core fields.\n","example":"name"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this core field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting. Each element must be a single character.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide per-field special characters to index for this core field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting. Each element must be a single character.\n"},"sortable":{"type":"boolean","description":"When set to true, enables sorting on this core field. Only supported for specific core fields.\n","example":true},"facetable":{"type":"boolean","description":"When set to true, enables faceting on this core field. A re-index is required for the change to take effect.\n","example":true}},"title":"CoreFieldOverride"}},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters used as token separators across the entire collection.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters indexed as part of tokens across the entire collection.\n"}},"title":"IndexableFieldsAttributes"},"meta":{"type":"object","required":["owner"],"properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"IndexableFieldsMeta"}},"title":"IndexableFields"}},"title":"IndexableFieldsResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"409":{"description":"Conflict - reindexing job queued or in progress","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create search profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create search profile"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/catalogs/search-profiles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new search profile.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"Represents the type of object being returned. Always `catalog_search_profile`.","type":"string","example":"catalog_search_profile","enum":["catalog_search_profile"],"title":"SearchProfileType"},"attributes":{"type":"object","required":["slug","description","fields","force_use_default_price_for_faceting_and_sorting"],"properties":{"slug":{"type":"string","description":"The unique slug of the search profile. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","example":"default","pattern":"^[a-zA-Z0-9_.-]+$","minLength":1},"description":{"type":"string","description":"The description of the search profile.","example":"Default search profile","default":""},"fields":{"type":"array","description":"A collection of search fields","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the search field.","example":"name","minLength":1},"weight":{"type":"integer","description":"The relative weight to give each field when ranking results. This can be used to boost fields in priority, when looking for matches.\nIf no explicit weights are provided for all fields, fields earlier in the fields list will be considered to have greater weight.\nIf no explicit weights are provided for some fields, the default weight of zero (0) will be used for the fields with no explicit weight.\n","example":10,"minimum":0,"maximum":15},"num_typos":{"type":"integer","description":"Per-field override for the maximum number of typographical errors [Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed\nwhen matching this field. Accepted values: 0 (exact match only), 1, or 2.\nOverrides `typo_tolerance.num_typos` for this field. Falls back to `typo_tolerance.num_typos`\nif set, otherwise default of 2.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`typo_tolerance.min_len_to_allow_single_character_correction` (default 4) and\n`typo_tolerance.min_len_to_allow_two_character_correction` (default 7):\n- A token shorter than the single-character threshold gets **no** typo correction, even with `num_typos` 1 or 2.\n- A token at least as long as the single-character threshold but shorter than the two-character threshold is corrected by **at most one** character, even with `num_typos` of 2.\n- Only tokens at least as long as the two-character threshold can use the full two corrections.\n\nFor example, with the defaults, \"appla\" → \"apple\" (length 5, one correction) is allowed,\nbut a 5-character query with two mistakes is not corrected even with `num_typos` of 2, because two-character correction requires a token of at least 7 characters.\n","minimum":0,"maximum":2,"example":1},"prefix":{"type":"boolean","description":"Per-field override for prefix (partial match) behavior on the last query token.\nWhen true, the last word is treated as a prefix; when false, it must match exactly.\nFor example, when true, a search request for \"red app\" matches \"red apple\".\nOverrides the profile-level `prefix` for this field. Falls back to the profile-level\n`prefix` if set, otherwise default of true.\n\nThe primary use case is to show results as the user is typing in the search box.\n","example":true}},"title":"SearchField"}},"text_match_type":{"type":"string","description":"When a search profile has multiple fields defined, this parameter determines how the representative text match score of a product is calculated.\n\n- `max_score (Default)`: In this mode, the products's representative score is simply the highest score from any single matching field. The field weights are used only as a tie-breaker if two products have the exact same highest score. This mode prioritizes the quality of the match in the single best-matching field.\n- `max_weight`: This mode uses the score from the matching field that has the highest weight. This means a partial, lower-quality match on a heavily weighted field (e.g., name) can be prioritized over a perfect match on a lower-weighted field (e.g., description). This mode prioritizes matches in the most important fields, regardless of match quality.\n- `sum_score`: This mode calculates a holistic score by summing the weighted scores from all matching fields. Its advantage is that it rewards products that match a query across multiple attributes. However, it carries the risk that a product with many weak, partial matches across several low-weighted fields could outrank a product with a single strong, perfect match in a high-weighted field.\n","enum":["max_score","max_weight","sum_score"],"example":"max_score","title":"TextMatchType"},"filters":{"type":"array","description":"Optional list of filter expressions to apply to search results. Multiple filters in the array are combined using OR logic (records matching filter1 || filter2 || ... filterN).\nTo combine conditions with AND logic, include multiple conditions within a single filter string (e.g., \"meta.search.categories.lvl1:=`All Products > Mens Shoes` && meta.display_price.without_tax.float_price:>100\").\nThese profile-level filters are ANDed with any filters provided in the search request via the filter_by parameter, resulting in: (profile_filter1 || profile_filter2 || ... profile_filterN) && request_filters.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"exclusions":{"type":"array","description":"A collection of exclusion expressions to apply to search results. Multiple exclusions in the array are combined using OR logic (records matching exclusion1 || exclusion2 || ... exclusionN).","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"boosts":{"type":"array","items":{"type":"object","description":"Defines a boosting rule that assigns a score to products matching a specific field value.","required":["condition","weight"],"properties":{"condition":{"type":"string","description":"A filter expression used to identify a subset of products for boosting. This follows the standard filter_by syntax.\n\nIt can be a simple condition like `meta.search.nodes.name:=\\`Electronics\\`` or complex like `meta.search.nodes.name:=\\`Electronics\\` && extensions.products(Details).brand:=Nike`.\n","minLength":1,"example":"meta.search.nodes.name:=\\`Electronics\\`"},"weight":{"type":"integer","description":"A numerical value representing the boost intensity. Products matching the criteria are assigned this value. Higher weights will cause products to appear earlier in the results.\n\n**Impact of Weights:**\n* **Boost (Positive):** Pushes products to the top.\n* **No affect (Zero):** Has no affect. Treated the same as products that match no rules.\n* **Bury (Negative):** Pushes products to the bottom.\n\n**Rule Evaluation:** The system uses \"Short-circuit\" evaluation. The engine stops at the **first matching rule**.\nThis means the weight of the first matching rule will be used as the product weight to sort the results.\nIf no rules match, the product is assigned a weight of `0`.\n","example":5}},"title":"SearchBoostRule"},"x-go-type-skip-optional-pointer":true},"prefix":{"type":"boolean","description":"Profile-level default for prefix (partial match) behavior on the last query token. When true, the last word in the query is treated as a prefix for all fields that do not have an explicit per-field prefix value. For example, a search request for \"red app\" matches \"red apple\". When false, the last word must match exactly. If omitted, default of true applies. Per-field prefix values override this setting.\nThe primary use case is to show results as the user is typing in the search box.\n","example":true},"typo_tolerance":{"type":"object","nullable":true,"description":"Optional typo tolerance configuration applied at search time.\nAll fields are optional; defaults are noted on each field.\n","properties":{"num_typos":{"type":"integer","description":"Profile-level default for the maximum number of typographical errors\n[Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed when matching any field.\nAccepted values: 0 (exact match only), 1, or 2.\nPer-field `num_typos` values override this setting. If omitted, default of 2 applies.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`min_len_to_allow_single_character_correction` (default 4) and\n`min_len_to_allow_two_character_correction` (default 7): a token shorter than the\nsingle-character threshold gets no correction at all, and a token shorter than the\ntwo-character threshold is corrected by at most one character — even when `num_typos` is 2.\nSee those two fields for details.\n","minimum":0,"maximum":2,"example":1},"min_len_to_allow_single_character_correction":{"type":"integer","description":"Minimum query-token length required before a single-character typo correction is attempted. This works together with `num_typos`: a token shorter than this length receives no typo correction at all, regardless of `num_typos`. For example, when set to 4, a search for \"appla\" will match \"apple\", but a search for \"apa\" will not match \"app\" because the length of \"apa\" is 3.\nDefault: 4.\n","minimum":1,"example":3},"min_len_to_allow_two_character_correction":{"type":"integer","description":"Minimum query-token length required before a two-character typo correction is attempted. This works together with `num_typos`: even when `num_typos` is 2, a token shorter than this length is corrected by at most one character (and a token shorter than `min_len_to_allow_single_character_correction` is not corrected at all). For example, with the default of 7, the 7-character query \"monetar\" can be corrected to \"monitor\" (two corrections), but a 6-character query with two mistakes cannot.\nDefault: 7\n","minimum":1,"example":7},"typo_tokens_threshold":{"type":"integer","description":"Typo-corrected query variations are only generated if the number of exact results\nfound is fewer than this value. Set to 0 to disable typo tolerance entirely.\nFor example, when set to 5 and the search result only has 3 results, the search engine will apply typo correction to try to return 5 or more results.\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_threshold":{"type":"integer","description":"For multi-word queries, tokens are progressively dropped if the number of results\nis fewer than this value. Set to 0 to disable token dropping.\n\nFor example, when set to 5 and the search result only has 3 results for \"red apple\" search,\nthe search engine will drop the last token \"apple\" and find more results with just by searching for \"red\".\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_mode":{"type":"string","description":"Controls the direction in which tokens are dropped from a multi-word query when\nresults fall below drop_tokens_threshold.\n- `right_to_left` (default): drops tokens from the right end of the query first.\n- `left_to_right`: drops tokens from the left end first.\n- `both_sides:N`: drops from both ends, limited to queries of N tokens or fewer\n  (e.g. `both_sides:3` applies only to queries with 3 or fewer tokens).\n","example":"right_to_left"},"enable_typos_for_numerical_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that are purely numeric (every character is a digit, e.g. \"98765\"). Such a token must then match exactly.\nDefault: true\n","example":true},"enable_typos_for_special_char_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that contain at least one non-alphanumeric character\n(any character outside `a-z`, `A-Z`, `0-9`), forcing such tokens to match exactly.\nUseful for keeping product codes / SKUs precise.\n\nTokens like `abc-123`, `abc-def`, `123-456`, and `v1.2.0` are affected;\na plain alphanumeric token like `abc123` is not.\n\nNote: the special character must be indexed on the field (via `symbols_to_index`);\notherwise the search engine removes the special characters from tokens\n(e.g. a token like v1.2.0 becomes v120) and it no longer qualifies.\n\nDefault: true\n","example":true},"split_join_tokens":{"type":"string","description":"Controls whether compound words and multi-word phrases are treated as equivalent during search.\nFor example, a query for \"nonstick\" may also match \"non stick\", and vice versa.\n- `fallback` (default): tries the original query form first; falls back to split/joined variants if results are insufficient.\n- `always`: always generates both split and joined token variants alongside the original query.\n- `off`: disables split/join token handling.\n","enum":["fallback","always","off"],"example":"fallback"}},"title":"TypoTolerance"},"synonym_settings":{"type":"object","nullable":true,"description":"Optional synonym tuning applied at search time. These settings control how synonym\nmatches are ranked and how query tokens are resolved against the synonym sets attached\nto the search profile. All fields are optional; defaults are noted on each field.\nThey only have an observable effect when synonym sets are attached to the resolved profile.\n","properties":{"demote_synonym_match":{"type":"boolean","description":"When true, results matched via a synonym are ranked below direct (non-synonym) matches. When false, synonym matches and direct matches are ranked equally.\nDefault: false\n","example":true},"synonym_resolution_allowed_on_prefix":{"type":"boolean","description":"When true, an incomplete (prefix) query token can resolve to a synonym, i.e. synonym\nexpansion is attempted on prefix tokens.\n\n**This is not the same as the `prefix` setting.** The `prefix` setting treats only the\n**last** word of the query as a prefix; `synonym_resolution_allowed_on_prefix` applies\nprefix matching at **every** token position when looking words up in the synonym sets —\nthere is no last-token special-casing.\n\n**Exact matches always win.** A query token that exactly equals a synonym key resolves\nregardless of this flag; the prefix behavior only affects the fuzzy fallback for tokens\nwith no exact synonym-key match. It composes with\n`number_of_typos_allowed_when_resolving_synonyms`, which governs typo tolerance during\nthe prefix/fuzzy lookup.\n\nWorked example (synonym keys `red`, `apple`, `apparel`):\n- `red app`: `red` matches exactly; `app` prefix-matches both `apple` and `apparel` — both expand.\n- `re app`: `re` prefix-matches `red` **and** `app` prefix-matches `apple`/`apparel` — both expand.\n  The regular `prefix` setting would only treat the last word (`app`) as a prefix; here every\n  position is prefix-matched.\n\nDefault: false\n","example":true},"number_of_typos_allowed_when_resolving_synonyms":{"type":"integer","description":"Number of typos allowed when resolving synonyms. Enables fuzzy synonym matching\nso that a misspelled query term can still trigger a synonym expansion for the\nsynonym sets attached to the search profile.\nAccepted values: 0 (exact synonym match only, default), 1, or 2.\n","minimum":0,"maximum":2,"example":0}},"title":"SynonymSettings"},"synonym_sets":{"type":"array","description":"Optional list of synonym set IDs to apply at search time. Each synonym set must exist and must have been synced to the search engine at least once. Organization-level search profiles may only reference organization-level synonym sets. Store-level search profiles may reference organization-level and same-store synonym sets.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"force_use_default_price_for_faceting_and_sorting":{"type":"boolean","description":"When set to true, the default price is used for faceting and sorting for segmented catalogs even if the catalog rule has a supported price book.","default":false,"example":true}},"title":"SearchProfileAttributes"}},"title":"SearchProfileCreateRequestData"}},"title":"SearchProfileCreateRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully created search profile","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the search profile.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_profile`.","type":"string","example":"catalog_search_profile","enum":["catalog_search_profile"],"title":"SearchProfileType"},"attributes":{"type":"object","required":["slug","description","fields","force_use_default_price_for_faceting_and_sorting"],"properties":{"slug":{"type":"string","description":"The unique slug of the search profile. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","example":"default","pattern":"^[a-zA-Z0-9_.-]+$","minLength":1},"description":{"type":"string","description":"The description of the search profile.","example":"Default search profile","default":""},"fields":{"type":"array","description":"A collection of search fields","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the search field.","example":"name","minLength":1},"weight":{"type":"integer","description":"The relative weight to give each field when ranking results. This can be used to boost fields in priority, when looking for matches.\nIf no explicit weights are provided for all fields, fields earlier in the fields list will be considered to have greater weight.\nIf no explicit weights are provided for some fields, the default weight of zero (0) will be used for the fields with no explicit weight.\n","example":10,"minimum":0,"maximum":15},"num_typos":{"type":"integer","description":"Per-field override for the maximum number of typographical errors [Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed\nwhen matching this field. Accepted values: 0 (exact match only), 1, or 2.\nOverrides `typo_tolerance.num_typos` for this field. Falls back to `typo_tolerance.num_typos`\nif set, otherwise default of 2.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`typo_tolerance.min_len_to_allow_single_character_correction` (default 4) and\n`typo_tolerance.min_len_to_allow_two_character_correction` (default 7):\n- A token shorter than the single-character threshold gets **no** typo correction, even with `num_typos` 1 or 2.\n- A token at least as long as the single-character threshold but shorter than the two-character threshold is corrected by **at most one** character, even with `num_typos` of 2.\n- Only tokens at least as long as the two-character threshold can use the full two corrections.\n\nFor example, with the defaults, \"appla\" → \"apple\" (length 5, one correction) is allowed,\nbut a 5-character query with two mistakes is not corrected even with `num_typos` of 2, because two-character correction requires a token of at least 7 characters.\n","minimum":0,"maximum":2,"example":1},"prefix":{"type":"boolean","description":"Per-field override for prefix (partial match) behavior on the last query token.\nWhen true, the last word is treated as a prefix; when false, it must match exactly.\nFor example, when true, a search request for \"red app\" matches \"red apple\".\nOverrides the profile-level `prefix` for this field. Falls back to the profile-level\n`prefix` if set, otherwise default of true.\n\nThe primary use case is to show results as the user is typing in the search box.\n","example":true}},"title":"SearchField"}},"text_match_type":{"type":"string","description":"When a search profile has multiple fields defined, this parameter determines how the representative text match score of a product is calculated.\n\n- `max_score (Default)`: In this mode, the products's representative score is simply the highest score from any single matching field. The field weights are used only as a tie-breaker if two products have the exact same highest score. This mode prioritizes the quality of the match in the single best-matching field.\n- `max_weight`: This mode uses the score from the matching field that has the highest weight. This means a partial, lower-quality match on a heavily weighted field (e.g., name) can be prioritized over a perfect match on a lower-weighted field (e.g., description). This mode prioritizes matches in the most important fields, regardless of match quality.\n- `sum_score`: This mode calculates a holistic score by summing the weighted scores from all matching fields. Its advantage is that it rewards products that match a query across multiple attributes. However, it carries the risk that a product with many weak, partial matches across several low-weighted fields could outrank a product with a single strong, perfect match in a high-weighted field.\n","enum":["max_score","max_weight","sum_score"],"example":"max_score","title":"TextMatchType"},"filters":{"type":"array","description":"Optional list of filter expressions to apply to search results. Multiple filters in the array are combined using OR logic (records matching filter1 || filter2 || ... filterN).\nTo combine conditions with AND logic, include multiple conditions within a single filter string (e.g., \"meta.search.categories.lvl1:=`All Products > Mens Shoes` && meta.display_price.without_tax.float_price:>100\").\nThese profile-level filters are ANDed with any filters provided in the search request via the filter_by parameter, resulting in: (profile_filter1 || profile_filter2 || ... profile_filterN) && request_filters.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"exclusions":{"type":"array","description":"A collection of exclusion expressions to apply to search results. Multiple exclusions in the array are combined using OR logic (records matching exclusion1 || exclusion2 || ... exclusionN).","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"boosts":{"type":"array","items":{"type":"object","description":"Defines a boosting rule that assigns a score to products matching a specific field value.","required":["condition","weight"],"properties":{"condition":{"type":"string","description":"A filter expression used to identify a subset of products for boosting. This follows the standard filter_by syntax.\n\nIt can be a simple condition like `meta.search.nodes.name:=\\`Electronics\\`` or complex like `meta.search.nodes.name:=\\`Electronics\\` && extensions.products(Details).brand:=Nike`.\n","minLength":1,"example":"meta.search.nodes.name:=\\`Electronics\\`"},"weight":{"type":"integer","description":"A numerical value representing the boost intensity. Products matching the criteria are assigned this value. Higher weights will cause products to appear earlier in the results.\n\n**Impact of Weights:**\n* **Boost (Positive):** Pushes products to the top.\n* **No affect (Zero):** Has no affect. Treated the same as products that match no rules.\n* **Bury (Negative):** Pushes products to the bottom.\n\n**Rule Evaluation:** The system uses \"Short-circuit\" evaluation. The engine stops at the **first matching rule**.\nThis means the weight of the first matching rule will be used as the product weight to sort the results.\nIf no rules match, the product is assigned a weight of `0`.\n","example":5}},"title":"SearchBoostRule"},"x-go-type-skip-optional-pointer":true},"prefix":{"type":"boolean","description":"Profile-level default for prefix (partial match) behavior on the last query token. When true, the last word in the query is treated as a prefix for all fields that do not have an explicit per-field prefix value. For example, a search request for \"red app\" matches \"red apple\". When false, the last word must match exactly. If omitted, default of true applies. Per-field prefix values override this setting.\nThe primary use case is to show results as the user is typing in the search box.\n","example":true},"typo_tolerance":{"type":"object","nullable":true,"description":"Optional typo tolerance configuration applied at search time.\nAll fields are optional; defaults are noted on each field.\n","properties":{"num_typos":{"type":"integer","description":"Profile-level default for the maximum number of typographical errors\n[Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed when matching any field.\nAccepted values: 0 (exact match only), 1, or 2.\nPer-field `num_typos` values override this setting. If omitted, default of 2 applies.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`min_len_to_allow_single_character_correction` (default 4) and\n`min_len_to_allow_two_character_correction` (default 7): a token shorter than the\nsingle-character threshold gets no correction at all, and a token shorter than the\ntwo-character threshold is corrected by at most one character — even when `num_typos` is 2.\nSee those two fields for details.\n","minimum":0,"maximum":2,"example":1},"min_len_to_allow_single_character_correction":{"type":"integer","description":"Minimum query-token length required before a single-character typo correction is attempted. This works together with `num_typos`: a token shorter than this length receives no typo correction at all, regardless of `num_typos`. For example, when set to 4, a search for \"appla\" will match \"apple\", but a search for \"apa\" will not match \"app\" because the length of \"apa\" is 3.\nDefault: 4.\n","minimum":1,"example":3},"min_len_to_allow_two_character_correction":{"type":"integer","description":"Minimum query-token length required before a two-character typo correction is attempted. This works together with `num_typos`: even when `num_typos` is 2, a token shorter than this length is corrected by at most one character (and a token shorter than `min_len_to_allow_single_character_correction` is not corrected at all). For example, with the default of 7, the 7-character query \"monetar\" can be corrected to \"monitor\" (two corrections), but a 6-character query with two mistakes cannot.\nDefault: 7\n","minimum":1,"example":7},"typo_tokens_threshold":{"type":"integer","description":"Typo-corrected query variations are only generated if the number of exact results\nfound is fewer than this value. Set to 0 to disable typo tolerance entirely.\nFor example, when set to 5 and the search result only has 3 results, the search engine will apply typo correction to try to return 5 or more results.\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_threshold":{"type":"integer","description":"For multi-word queries, tokens are progressively dropped if the number of results\nis fewer than this value. Set to 0 to disable token dropping.\n\nFor example, when set to 5 and the search result only has 3 results for \"red apple\" search,\nthe search engine will drop the last token \"apple\" and find more results with just by searching for \"red\".\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_mode":{"type":"string","description":"Controls the direction in which tokens are dropped from a multi-word query when\nresults fall below drop_tokens_threshold.\n- `right_to_left` (default): drops tokens from the right end of the query first.\n- `left_to_right`: drops tokens from the left end first.\n- `both_sides:N`: drops from both ends, limited to queries of N tokens or fewer\n  (e.g. `both_sides:3` applies only to queries with 3 or fewer tokens).\n","example":"right_to_left"},"enable_typos_for_numerical_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that are purely numeric (every character is a digit, e.g. \"98765\"). Such a token must then match exactly.\nDefault: true\n","example":true},"enable_typos_for_special_char_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that contain at least one non-alphanumeric character\n(any character outside `a-z`, `A-Z`, `0-9`), forcing such tokens to match exactly.\nUseful for keeping product codes / SKUs precise.\n\nTokens like `abc-123`, `abc-def`, `123-456`, and `v1.2.0` are affected;\na plain alphanumeric token like `abc123` is not.\n\nNote: the special character must be indexed on the field (via `symbols_to_index`);\notherwise the search engine removes the special characters from tokens\n(e.g. a token like v1.2.0 becomes v120) and it no longer qualifies.\n\nDefault: true\n","example":true},"split_join_tokens":{"type":"string","description":"Controls whether compound words and multi-word phrases are treated as equivalent during search.\nFor example, a query for \"nonstick\" may also match \"non stick\", and vice versa.\n- `fallback` (default): tries the original query form first; falls back to split/joined variants if results are insufficient.\n- `always`: always generates both split and joined token variants alongside the original query.\n- `off`: disables split/join token handling.\n","enum":["fallback","always","off"],"example":"fallback"}},"title":"TypoTolerance"},"synonym_settings":{"type":"object","nullable":true,"description":"Optional synonym tuning applied at search time. These settings control how synonym\nmatches are ranked and how query tokens are resolved against the synonym sets attached\nto the search profile. All fields are optional; defaults are noted on each field.\nThey only have an observable effect when synonym sets are attached to the resolved profile.\n","properties":{"demote_synonym_match":{"type":"boolean","description":"When true, results matched via a synonym are ranked below direct (non-synonym) matches. When false, synonym matches and direct matches are ranked equally.\nDefault: false\n","example":true},"synonym_resolution_allowed_on_prefix":{"type":"boolean","description":"When true, an incomplete (prefix) query token can resolve to a synonym, i.e. synonym\nexpansion is attempted on prefix tokens.\n\n**This is not the same as the `prefix` setting.** The `prefix` setting treats only the\n**last** word of the query as a prefix; `synonym_resolution_allowed_on_prefix` applies\nprefix matching at **every** token position when looking words up in the synonym sets —\nthere is no last-token special-casing.\n\n**Exact matches always win.** A query token that exactly equals a synonym key resolves\nregardless of this flag; the prefix behavior only affects the fuzzy fallback for tokens\nwith no exact synonym-key match. It composes with\n`number_of_typos_allowed_when_resolving_synonyms`, which governs typo tolerance during\nthe prefix/fuzzy lookup.\n\nWorked example (synonym keys `red`, `apple`, `apparel`):\n- `red app`: `red` matches exactly; `app` prefix-matches both `apple` and `apparel` — both expand.\n- `re app`: `re` prefix-matches `red` **and** `app` prefix-matches `apple`/`apparel` — both expand.\n  The regular `prefix` setting would only treat the last word (`app`) as a prefix; here every\n  position is prefix-matched.\n\nDefault: false\n","example":true},"number_of_typos_allowed_when_resolving_synonyms":{"type":"integer","description":"Number of typos allowed when resolving synonyms. Enables fuzzy synonym matching\nso that a misspelled query term can still trigger a synonym expansion for the\nsynonym sets attached to the search profile.\nAccepted values: 0 (exact synonym match only, default), 1, or 2.\n","minimum":0,"maximum":2,"example":0}},"title":"SynonymSettings"},"synonym_sets":{"type":"array","description":"Optional list of synonym set IDs to apply at search time. Each synonym set must exist and must have been synced to the search engine at least once. Organization-level search profiles may only reference organization-level synonym sets. Store-level search profiles may reference organization-level and same-store synonym sets.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"force_use_default_price_for_faceting_and_sorting":{"type":"boolean","description":"When set to true, the default price is used for faceting and sorting for segmented catalogs even if the catalog rule has a supported price book.","default":false,"example":true}},"title":"SearchProfileAttributes"},"meta":{"type":"object","required":["default","owner"],"properties":{"default":{"type":"boolean","description":"Whether this is the default search profile.","example":true},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"SearchProfileMeta"}},"title":"SearchProfile"}},"title":"SearchProfileResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create stopword set

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create stopword set"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/catalogs/search/stopword-sets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new stopwords set.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_stopword_set`.","example":"catalog_search_stopword_set","enum":["catalog_search_stopword_set"],"title":"StopwordSetType"},"attributes":{"type":"object","required":["stopwords"],"properties":{"locale":{"type":"string","description":"[ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for the stopwords set. Omit or pass null for the default set. At most one stopwords set per locale is allowed.\n","example":"en"},"stopwords":{"type":"array","description":"The list of stopwords.","items":{"type":"string"},"minItems":1,"example":["the","a","an","is"]}},"title":"StopwordSetAttributes"}}}},"title":"CreateStopwordSetRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully created stopword set","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the stopword set.","type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_stopword_set`.","example":"catalog_search_stopword_set","enum":["catalog_search_stopword_set"],"title":"StopwordSetType"},"attributes":{"type":"object","required":["stopwords"],"properties":{"locale":{"type":"string","description":"[ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for the stopwords set. Omit or pass null for the default set. At most one stopwords set per locale is allowed.\n","example":"en"},"stopwords":{"type":"array","description":"The list of stopwords.","items":{"type":"string"},"minItems":1,"example":["the","a","an","is"]}},"title":"StopwordSetAttributes"},"meta":{"type":"object","required":["created_at","updated_at","owner","sync_status"],"properties":{"created_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was created.","example":"2026-03-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was last updated.","example":"2026-03-05T12:00:00Z"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"},"sync_status":{"type":"string","description":"The sync status of the stopword set.","enum":["pending_sync","synced","sync_failed","pending_delete"],"example":"pending_sync","x-go-type":"model.SyncStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}},"last_synced_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was last successfully synced.","example":"2026-03-05T12:01:00Z"}},"title":"StopwordSetMeta"}},"title":"StopwordSet"}},"title":"StopwordSetResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"409":{"description":"Conflict - a stopwords set for the given locale already exists","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create synonym set

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create synonym set"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/catalogs/search/synonym-sets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new synonym set.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_synonym_set`.","example":"catalog_search_synonym_set","enum":["catalog_search_synonym_set"],"title":"SynonymSetType"},"attributes":{"type":"object","required":["name","items"],"properties":{"name":{"type":"string","description":"Human-readable name for the synonym set.","example":"Apparel terms"},"items":{"type":"array","description":"The synonym items in this set.","items":{"type":"object","required":["id","synonyms"],"properties":{"id":{"type":"string","description":"Unique identifier for the synonym item within the set. Alphanumeric, hyphen, and underscore only.","pattern":"^[a-zA-Z0-9_-]+$","example":"footwear-terms","x-go-name":"ID"},"synonyms":{"type":"array","description":"List of synonym terms.","items":{"type":"string"},"minItems":1,"example":["sneakers","trainers","running shoes"]},"root":{"type":"string","description":"Makes this a one-way synonym. Searches for root also match synonyms, but not vice versa.","example":"jacket"},"locale":{"type":"string","description":"[ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for this synonym item.\n","example":"en"},"symbols_to_index":{"type":"array","description":"Symbols to index for this synonym item. Each element must be exactly one character.","items":{"type":"string","minLength":1,"maxLength":1},"example":["-"],"x-go-type-skip-optional-pointer":true}},"title":"SynonymSetItem"},"minItems":1}},"title":"SynonymSetAttributes"}}}},"title":"CreateSynonymSetRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully created synonym set","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the synonym set.","type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_synonym_set`.","example":"catalog_search_synonym_set","enum":["catalog_search_synonym_set"],"title":"SynonymSetType"},"attributes":{"type":"object","required":["name","items"],"properties":{"name":{"type":"string","description":"Human-readable name for the synonym set.","example":"Apparel terms"},"items":{"type":"array","description":"The synonym items in this set.","items":{"type":"object","required":["id","synonyms"],"properties":{"id":{"type":"string","description":"Unique identifier for the synonym item within the set. Alphanumeric, hyphen, and underscore only.","pattern":"^[a-zA-Z0-9_-]+$","example":"footwear-terms","x-go-name":"ID"},"synonyms":{"type":"array","description":"List of synonym terms.","items":{"type":"string"},"minItems":1,"example":["sneakers","trainers","running shoes"]},"root":{"type":"string","description":"Makes this a one-way synonym. Searches for root also match synonyms, but not vice versa.","example":"jacket"},"locale":{"type":"string","description":"[ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for this synonym item.\n","example":"en"},"symbols_to_index":{"type":"array","description":"Symbols to index for this synonym item. Each element must be exactly one character.","items":{"type":"string","minLength":1,"maxLength":1},"example":["-"],"x-go-type-skip-optional-pointer":true}},"title":"SynonymSetItem"},"minItems":1}},"title":"SynonymSetAttributes"},"meta":{"type":"object","required":["created_at","updated_at","owner","sync_status"],"properties":{"created_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was created.","example":"2026-03-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was last updated.","example":"2026-03-05T12:00:00Z"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"},"sync_status":{"type":"string","description":"The sync status of the synonym set.","enum":["pending_sync","synced","sync_failed","pending_delete"],"example":"pending_sync","x-go-type":"model.SyncStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}},"last_synced_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was last successfully synced.","example":"2026-03-05T12:01:00Z"}},"title":"SynonymSetMeta"}},"title":"SynonymSet"}},"title":"SynonymSetResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete indexable fields

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete indexable fields"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/catalogs/indexable-fields/{indexable_fields_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete additional fields to be indexed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"indexable_fields_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the indexable fields","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"IndexableFieldsID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Successfully deleted indexable fields"},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"403":{"description":"Permission denied - indexable fields owned by the organization","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"409":{"description":"Conflict - reindexing job queued or in progress","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete search profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete search profile"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/catalogs/search-profiles/{search_profile_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a search profile.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"search_profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the search profile","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"ProfileID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Successfully deleted search profile"},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"403":{"description":"Permission denied - search profile owned by the organization","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete stopword set

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete stopword set"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/catalogs/search/stopword-sets/{stopword_set_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a stopword set by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"stopword_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the stopword set","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"StopwordSetID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Stopword set marked for deletion"},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete synonym set

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete synonym set"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/catalogs/search/synonym-sets/{synonym_set_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a synonym set by ID. A synonym set cannot be deleted while it is being used by any search profile.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"synonym_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the synonym set","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"SynonymSetID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Synonym set marked for deletion"},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"409":{"description":"Conflict - synonym set is referenced by a search profile","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get indexable fields

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get indexable fields"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/indexable-fields/{indexable_fields_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get additional fields to be indexed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"indexable_fields_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the indexable fields","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"IndexableFieldsID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Get indexable fields","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier of the indexable fields.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_indexable_fields`.","type":"string","example":"catalog_search_indexable_fields","enum":["catalog_search_indexable_fields"],"title":"IndexableFieldsType"},"attributes":{"type":"object","properties":{"fields":{"type":"array","x-go-type-skip-optional-pointer":true,"description":"A collection of indexable fields","title":"IndexableFields","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","description":"The name of the field.","example":"extensions.products(clothing).color","minLength":1},"type":{"type":"string","description":"The type of the field.","enum":["string","int32","int64","bool","float"],"example":"string","x-go-type":"model.FieldType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"},"title":"FieldType"},"facetable":{"type":"boolean","description":"Enables faceting on the field.","default":false,"example":true},"sortable":{"type":"boolean","description":"When set to true, the field will be sortable. Default: true for numbers, false otherwise.","example":true},"locale":{"type":"string","description":"For configuring language specific tokenization, e.g. jp for Japanese. Default: en which also broadly supports most European languages. For valid values, see [ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).","default":"en","example":"en"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Provide per-field special characters to index for this field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting.\n"}},"title":"IndexableField"},"example":[{"name":"extensions.products(clothing).color","type":"string","facetable":false,"sortable":false,"locale":"en"},{"name":"shopper_attributes.fabric","type":"string","facetable":false,"sortable":false},{"name":"admin_attributes.internal_grade","type":"string","sortable":true}]},"core_field_overrides":{"type":"array","x-go-type-skip-optional-pointer":true,"description":"Per-field configuration for core product fields (e.g. name, description).","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the core field to configure. Must be one of the supported core fields.\n","example":"name"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this core field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting. Each element must be a single character.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide per-field special characters to index for this core field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting. Each element must be a single character.\n"},"sortable":{"type":"boolean","description":"When set to true, enables sorting on this core field. Only supported for specific core fields.\n","example":true},"facetable":{"type":"boolean","description":"When set to true, enables faceting on this core field. A re-index is required for the change to take effect.\n","example":true}},"title":"CoreFieldOverride"}},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters used as token separators across the entire collection.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters indexed as part of tokens across the entire collection.\n"}},"title":"IndexableFieldsAttributes"},"meta":{"type":"object","required":["owner"],"properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"IndexableFieldsMeta"}},"title":"IndexableFields"}},"title":"IndexableFieldsResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"404":{"description":"Indexable fields not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get search profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get search profile"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/search-profiles/{search_profile_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a search profile.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"search_profile_id","in":"path","required":true,"schema":{"type":"string"},"description":"The unique ID of the search profile or 'default' to retrieve the default search profile.","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"ProfileID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully retrieved search profile","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the search profile.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_profile`.","type":"string","example":"catalog_search_profile","enum":["catalog_search_profile"],"title":"SearchProfileType"},"attributes":{"type":"object","required":["slug","description","fields","force_use_default_price_for_faceting_and_sorting"],"properties":{"slug":{"type":"string","description":"The unique slug of the search profile. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","example":"default","pattern":"^[a-zA-Z0-9_.-]+$","minLength":1},"description":{"type":"string","description":"The description of the search profile.","example":"Default search profile","default":""},"fields":{"type":"array","description":"A collection of search fields","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the search field.","example":"name","minLength":1},"weight":{"type":"integer","description":"The relative weight to give each field when ranking results. This can be used to boost fields in priority, when looking for matches.\nIf no explicit weights are provided for all fields, fields earlier in the fields list will be considered to have greater weight.\nIf no explicit weights are provided for some fields, the default weight of zero (0) will be used for the fields with no explicit weight.\n","example":10,"minimum":0,"maximum":15},"num_typos":{"type":"integer","description":"Per-field override for the maximum number of typographical errors [Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed\nwhen matching this field. Accepted values: 0 (exact match only), 1, or 2.\nOverrides `typo_tolerance.num_typos` for this field. Falls back to `typo_tolerance.num_typos`\nif set, otherwise default of 2.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`typo_tolerance.min_len_to_allow_single_character_correction` (default 4) and\n`typo_tolerance.min_len_to_allow_two_character_correction` (default 7):\n- A token shorter than the single-character threshold gets **no** typo correction, even with `num_typos` 1 or 2.\n- A token at least as long as the single-character threshold but shorter than the two-character threshold is corrected by **at most one** character, even with `num_typos` of 2.\n- Only tokens at least as long as the two-character threshold can use the full two corrections.\n\nFor example, with the defaults, \"appla\" → \"apple\" (length 5, one correction) is allowed,\nbut a 5-character query with two mistakes is not corrected even with `num_typos` of 2, because two-character correction requires a token of at least 7 characters.\n","minimum":0,"maximum":2,"example":1},"prefix":{"type":"boolean","description":"Per-field override for prefix (partial match) behavior on the last query token.\nWhen true, the last word is treated as a prefix; when false, it must match exactly.\nFor example, when true, a search request for \"red app\" matches \"red apple\".\nOverrides the profile-level `prefix` for this field. Falls back to the profile-level\n`prefix` if set, otherwise default of true.\n\nThe primary use case is to show results as the user is typing in the search box.\n","example":true}},"title":"SearchField"}},"text_match_type":{"type":"string","description":"When a search profile has multiple fields defined, this parameter determines how the representative text match score of a product is calculated.\n\n- `max_score (Default)`: In this mode, the products's representative score is simply the highest score from any single matching field. The field weights are used only as a tie-breaker if two products have the exact same highest score. This mode prioritizes the quality of the match in the single best-matching field.\n- `max_weight`: This mode uses the score from the matching field that has the highest weight. This means a partial, lower-quality match on a heavily weighted field (e.g., name) can be prioritized over a perfect match on a lower-weighted field (e.g., description). This mode prioritizes matches in the most important fields, regardless of match quality.\n- `sum_score`: This mode calculates a holistic score by summing the weighted scores from all matching fields. Its advantage is that it rewards products that match a query across multiple attributes. However, it carries the risk that a product with many weak, partial matches across several low-weighted fields could outrank a product with a single strong, perfect match in a high-weighted field.\n","enum":["max_score","max_weight","sum_score"],"example":"max_score","title":"TextMatchType"},"filters":{"type":"array","description":"Optional list of filter expressions to apply to search results. Multiple filters in the array are combined using OR logic (records matching filter1 || filter2 || ... filterN).\nTo combine conditions with AND logic, include multiple conditions within a single filter string (e.g., \"meta.search.categories.lvl1:=`All Products > Mens Shoes` && meta.display_price.without_tax.float_price:>100\").\nThese profile-level filters are ANDed with any filters provided in the search request via the filter_by parameter, resulting in: (profile_filter1 || profile_filter2 || ... profile_filterN) && request_filters.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"exclusions":{"type":"array","description":"A collection of exclusion expressions to apply to search results. Multiple exclusions in the array are combined using OR logic (records matching exclusion1 || exclusion2 || ... exclusionN).","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"boosts":{"type":"array","items":{"type":"object","description":"Defines a boosting rule that assigns a score to products matching a specific field value.","required":["condition","weight"],"properties":{"condition":{"type":"string","description":"A filter expression used to identify a subset of products for boosting. This follows the standard filter_by syntax.\n\nIt can be a simple condition like `meta.search.nodes.name:=\\`Electronics\\`` or complex like `meta.search.nodes.name:=\\`Electronics\\` && extensions.products(Details).brand:=Nike`.\n","minLength":1,"example":"meta.search.nodes.name:=\\`Electronics\\`"},"weight":{"type":"integer","description":"A numerical value representing the boost intensity. Products matching the criteria are assigned this value. Higher weights will cause products to appear earlier in the results.\n\n**Impact of Weights:**\n* **Boost (Positive):** Pushes products to the top.\n* **No affect (Zero):** Has no affect. Treated the same as products that match no rules.\n* **Bury (Negative):** Pushes products to the bottom.\n\n**Rule Evaluation:** The system uses \"Short-circuit\" evaluation. The engine stops at the **first matching rule**.\nThis means the weight of the first matching rule will be used as the product weight to sort the results.\nIf no rules match, the product is assigned a weight of `0`.\n","example":5}},"title":"SearchBoostRule"},"x-go-type-skip-optional-pointer":true},"prefix":{"type":"boolean","description":"Profile-level default for prefix (partial match) behavior on the last query token. When true, the last word in the query is treated as a prefix for all fields that do not have an explicit per-field prefix value. For example, a search request for \"red app\" matches \"red apple\". When false, the last word must match exactly. If omitted, default of true applies. Per-field prefix values override this setting.\nThe primary use case is to show results as the user is typing in the search box.\n","example":true},"typo_tolerance":{"type":"object","nullable":true,"description":"Optional typo tolerance configuration applied at search time.\nAll fields are optional; defaults are noted on each field.\n","properties":{"num_typos":{"type":"integer","description":"Profile-level default for the maximum number of typographical errors\n[Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed when matching any field.\nAccepted values: 0 (exact match only), 1, or 2.\nPer-field `num_typos` values override this setting. If omitted, default of 2 applies.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`min_len_to_allow_single_character_correction` (default 4) and\n`min_len_to_allow_two_character_correction` (default 7): a token shorter than the\nsingle-character threshold gets no correction at all, and a token shorter than the\ntwo-character threshold is corrected by at most one character — even when `num_typos` is 2.\nSee those two fields for details.\n","minimum":0,"maximum":2,"example":1},"min_len_to_allow_single_character_correction":{"type":"integer","description":"Minimum query-token length required before a single-character typo correction is attempted. This works together with `num_typos`: a token shorter than this length receives no typo correction at all, regardless of `num_typos`. For example, when set to 4, a search for \"appla\" will match \"apple\", but a search for \"apa\" will not match \"app\" because the length of \"apa\" is 3.\nDefault: 4.\n","minimum":1,"example":3},"min_len_to_allow_two_character_correction":{"type":"integer","description":"Minimum query-token length required before a two-character typo correction is attempted. This works together with `num_typos`: even when `num_typos` is 2, a token shorter than this length is corrected by at most one character (and a token shorter than `min_len_to_allow_single_character_correction` is not corrected at all). For example, with the default of 7, the 7-character query \"monetar\" can be corrected to \"monitor\" (two corrections), but a 6-character query with two mistakes cannot.\nDefault: 7\n","minimum":1,"example":7},"typo_tokens_threshold":{"type":"integer","description":"Typo-corrected query variations are only generated if the number of exact results\nfound is fewer than this value. Set to 0 to disable typo tolerance entirely.\nFor example, when set to 5 and the search result only has 3 results, the search engine will apply typo correction to try to return 5 or more results.\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_threshold":{"type":"integer","description":"For multi-word queries, tokens are progressively dropped if the number of results\nis fewer than this value. Set to 0 to disable token dropping.\n\nFor example, when set to 5 and the search result only has 3 results for \"red apple\" search,\nthe search engine will drop the last token \"apple\" and find more results with just by searching for \"red\".\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_mode":{"type":"string","description":"Controls the direction in which tokens are dropped from a multi-word query when\nresults fall below drop_tokens_threshold.\n- `right_to_left` (default): drops tokens from the right end of the query first.\n- `left_to_right`: drops tokens from the left end first.\n- `both_sides:N`: drops from both ends, limited to queries of N tokens or fewer\n  (e.g. `both_sides:3` applies only to queries with 3 or fewer tokens).\n","example":"right_to_left"},"enable_typos_for_numerical_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that are purely numeric (every character is a digit, e.g. \"98765\"). Such a token must then match exactly.\nDefault: true\n","example":true},"enable_typos_for_special_char_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that contain at least one non-alphanumeric character\n(any character outside `a-z`, `A-Z`, `0-9`), forcing such tokens to match exactly.\nUseful for keeping product codes / SKUs precise.\n\nTokens like `abc-123`, `abc-def`, `123-456`, and `v1.2.0` are affected;\na plain alphanumeric token like `abc123` is not.\n\nNote: the special character must be indexed on the field (via `symbols_to_index`);\notherwise the search engine removes the special characters from tokens\n(e.g. a token like v1.2.0 becomes v120) and it no longer qualifies.\n\nDefault: true\n","example":true},"split_join_tokens":{"type":"string","description":"Controls whether compound words and multi-word phrases are treated as equivalent during search.\nFor example, a query for \"nonstick\" may also match \"non stick\", and vice versa.\n- `fallback` (default): tries the original query form first; falls back to split/joined variants if results are insufficient.\n- `always`: always generates both split and joined token variants alongside the original query.\n- `off`: disables split/join token handling.\n","enum":["fallback","always","off"],"example":"fallback"}},"title":"TypoTolerance"},"synonym_settings":{"type":"object","nullable":true,"description":"Optional synonym tuning applied at search time. These settings control how synonym\nmatches are ranked and how query tokens are resolved against the synonym sets attached\nto the search profile. All fields are optional; defaults are noted on each field.\nThey only have an observable effect when synonym sets are attached to the resolved profile.\n","properties":{"demote_synonym_match":{"type":"boolean","description":"When true, results matched via a synonym are ranked below direct (non-synonym) matches. When false, synonym matches and direct matches are ranked equally.\nDefault: false\n","example":true},"synonym_resolution_allowed_on_prefix":{"type":"boolean","description":"When true, an incomplete (prefix) query token can resolve to a synonym, i.e. synonym\nexpansion is attempted on prefix tokens.\n\n**This is not the same as the `prefix` setting.** The `prefix` setting treats only the\n**last** word of the query as a prefix; `synonym_resolution_allowed_on_prefix` applies\nprefix matching at **every** token position when looking words up in the synonym sets —\nthere is no last-token special-casing.\n\n**Exact matches always win.** A query token that exactly equals a synonym key resolves\nregardless of this flag; the prefix behavior only affects the fuzzy fallback for tokens\nwith no exact synonym-key match. It composes with\n`number_of_typos_allowed_when_resolving_synonyms`, which governs typo tolerance during\nthe prefix/fuzzy lookup.\n\nWorked example (synonym keys `red`, `apple`, `apparel`):\n- `red app`: `red` matches exactly; `app` prefix-matches both `apple` and `apparel` — both expand.\n- `re app`: `re` prefix-matches `red` **and** `app` prefix-matches `apple`/`apparel` — both expand.\n  The regular `prefix` setting would only treat the last word (`app`) as a prefix; here every\n  position is prefix-matched.\n\nDefault: false\n","example":true},"number_of_typos_allowed_when_resolving_synonyms":{"type":"integer","description":"Number of typos allowed when resolving synonyms. Enables fuzzy synonym matching\nso that a misspelled query term can still trigger a synonym expansion for the\nsynonym sets attached to the search profile.\nAccepted values: 0 (exact synonym match only, default), 1, or 2.\n","minimum":0,"maximum":2,"example":0}},"title":"SynonymSettings"},"synonym_sets":{"type":"array","description":"Optional list of synonym set IDs to apply at search time. Each synonym set must exist and must have been synced to the search engine at least once. Organization-level search profiles may only reference organization-level synonym sets. Store-level search profiles may reference organization-level and same-store synonym sets.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"force_use_default_price_for_faceting_and_sorting":{"type":"boolean","description":"When set to true, the default price is used for faceting and sorting for segmented catalogs even if the catalog rule has a supported price book.","default":false,"example":true}},"title":"SearchProfileAttributes"},"meta":{"type":"object","required":["default","owner"],"properties":{"default":{"type":"boolean","description":"Whether this is the default search profile.","example":true},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"SearchProfileMeta"}},"title":"SearchProfile"}},"title":"SearchProfileResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"404":{"description":"Search profile not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get stopword set

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get stopword set"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/search/stopword-sets/{stopword_set_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a stopwords set by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"stopword_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the stopword set","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"StopwordSetID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully retrieved stopword set","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the stopword set.","type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_stopword_set`.","example":"catalog_search_stopword_set","enum":["catalog_search_stopword_set"],"title":"StopwordSetType"},"attributes":{"type":"object","required":["stopwords"],"properties":{"locale":{"type":"string","description":"[ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for the stopwords set. Omit or pass null for the default set. At most one stopwords set per locale is allowed.\n","example":"en"},"stopwords":{"type":"array","description":"The list of stopwords.","items":{"type":"string"},"minItems":1,"example":["the","a","an","is"]}},"title":"StopwordSetAttributes"},"meta":{"type":"object","required":["created_at","updated_at","owner","sync_status"],"properties":{"created_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was created.","example":"2026-03-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was last updated.","example":"2026-03-05T12:00:00Z"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"},"sync_status":{"type":"string","description":"The sync status of the stopword set.","enum":["pending_sync","synced","sync_failed","pending_delete"],"example":"pending_sync","x-go-type":"model.SyncStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}},"last_synced_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was last successfully synced.","example":"2026-03-05T12:01:00Z"}},"title":"StopwordSetMeta"}},"title":"StopwordSet"}},"title":"StopwordSetResponse"}}}},"404":{"description":"Stopword set not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get synonym set

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get synonym set"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/search/synonym-sets/{synonym_set_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a synonym set by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"synonym_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the synonym set","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"SynonymSetID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully retrieved synonym set","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the synonym set.","type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_synonym_set`.","example":"catalog_search_synonym_set","enum":["catalog_search_synonym_set"],"title":"SynonymSetType"},"attributes":{"type":"object","required":["name","items"],"properties":{"name":{"type":"string","description":"Human-readable name for the synonym set.","example":"Apparel terms"},"items":{"type":"array","description":"The synonym items in this set.","items":{"type":"object","required":["id","synonyms"],"properties":{"id":{"type":"string","description":"Unique identifier for the synonym item within the set. Alphanumeric, hyphen, and underscore only.","pattern":"^[a-zA-Z0-9_-]+$","example":"footwear-terms","x-go-name":"ID"},"synonyms":{"type":"array","description":"List of synonym terms.","items":{"type":"string"},"minItems":1,"example":["sneakers","trainers","running shoes"]},"root":{"type":"string","description":"Makes this a one-way synonym. Searches for root also match synonyms, but not vice versa.","example":"jacket"},"locale":{"type":"string","description":"[ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for this synonym item.\n","example":"en"},"symbols_to_index":{"type":"array","description":"Symbols to index for this synonym item. Each element must be exactly one character.","items":{"type":"string","minLength":1,"maxLength":1},"example":["-"],"x-go-type-skip-optional-pointer":true}},"title":"SynonymSetItem"},"minItems":1}},"title":"SynonymSetAttributes"},"meta":{"type":"object","required":["created_at","updated_at","owner","sync_status"],"properties":{"created_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was created.","example":"2026-03-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was last updated.","example":"2026-03-05T12:00:00Z"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"},"sync_status":{"type":"string","description":"The sync status of the synonym set.","enum":["pending_sync","synced","sync_failed","pending_delete"],"example":"pending_sync","x-go-type":"model.SyncStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}},"last_synced_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was last successfully synced.","example":"2026-03-05T12:01:00Z"}},"title":"SynonymSetMeta"}},"title":"SynonymSet"}},"title":"SynonymSetResponse"}}}},"404":{"description":"Synonym set not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Indexable Fields

Indexable Fields allow you to extend and fine-tune the search schema. By default, the search index includes all the core product fields like name, description, SKU, slug etc. Indexable Fields let you:

- **Add custom fields** to the index from product extension templates or custom (shopper and admin) attributes
- **Configure core field behavior** such as stemming and tokenization on built-in fields like `name` and `description`
- **Control tokenization** at the collection or per-field level using token separators and symbols to index

### When to Use Indexable Fields

Use Indexable Fields when you want to:

- **Search custom attributes**: Enable full-text search on custom product fields like brand, material, or specifications
- **Filter by custom attributes**: Allow shoppers to filter products by custom fields like color, size, or rating
- **Facet on custom attributes**: Display aggregated counts for custom field values in your navigation
- **Sort by custom attributes**: Order search results by custom numeric fields like rating or popularity
- **Enable stemming**: Match different word forms (e.g., "running" also matches "run", "runs") on both custom or core fields
- **Customize tokenization**: Control how hyphenated, compound, or symbol-containing text is split and indexed

### How Indexable Fields Work

1. **Create indexable fields**: Define custom fields to index and configure collection-level or per-field tokenization settings
2. **Override core field behavior**: Use `core_field_overrides` to configure stemming, token separators, or symbols to index on built-in fields like `name` and `description`
3. **Reindex catalogs**: After creating or modifying indexable fields, reindex your catalog releases to apply the changes
4. **Use in searches**: Once reindexed, custom fields are available in search queries for filtering, faceting, and sorting

### Field Configuration

Each entry in the custom fields (`fields` array) supports the following options:

| Option             | Description                                                                                               |
|--------------------|-----------------------------------------------------------------------------------------------------------|
| `name`             | The field path — see **Field Types** below for supported formats                                          |
| `facetable`        | When `true`, the field can be used for faceting to show aggregated value counts                           |
| `sortable`         | When `true`, the field can be used for sorting results                                                    |
| `locale`           | Language code for text tokenization, defaults to `en` for English                                         |
| `stem`             | When `true`, enables word stemming using the Snowball stemmer — see **Stemming** below                    |
| `token_separators` | Per-field characters to use as token separators, overriding the collection-level setting                  |
| `symbols_to_index` | Per-field special characters to preserve as part of tokens, overriding the collection-level setting       |

### Field Types

Two categories of fields can be indexed:

#### Extension Fields

Fields from your product extension templates, following the pattern `extensions.products(<template_slug>).<field_name>`:

- `<template_slug>` is the slug of your product extension template
- `<field_name>` is the name of the field within that template
- The field must exist and be enabled in the flows service
- Only enumerated string fields, numeric fields, and boolean fields can be faceted

**Example**: For a product extension template with slug `Details` containing a field `brand`, the indexable field name would be `extensions.products(Details).brand`.

#### Custom Attribute Fields

Merchant-defined key/value attributes stored directly on products:

- `shopper_attributes.<attribute_name>` — visible in shopper and admin catalog API responses and available for filtering, sorting, and faceting in both shopper and admin search
- `admin_attributes.<attribute_name>` — available for filtering and sorting in both shopper and admin search; not returned in search response payloads
- `<attribute_name>` must be no longer than **64 characters** and can only contain alphanumeric characters, underscores (`_`), and hyphens (`-`).
- Attribute fields are always typed as `string`
- Faceting and sorting can be enabled

**Examples**: `shopper_attributes.fabric`, `admin_attributes.internal_grade`

### Core Field Overrides

In addition to configuring custom fields, Indexable Fields can influence the behavior of built-in product fields such as `name`, `description`, and `sku`. Use the `core_field_overrides` to apply per-field settings.

Each entry in `core_field_overrides` supports `stem`, `token_separators`, `symbols_to_index`, `sortable`, and `facetable`. This is useful when you want to enable stemming on the product description, apply custom tokenization to a specific core field, or enable sorting on fields like `name` and `sku`.

**Example**: Enable stemming on `description` and treat hyphens as token separators only on `name`:

```json
{
  "core_field_overrides": [
    { "name": "description", "stem": true },
    { "name": "name", "token_separators": ["-"], "sortable": true }
  ]
}
```

### Stemming

Stemming reduces words to their root form at both index and query time, so a search for "running" also matches products containing "run", "runs", or "runner". This improves search recall for descriptive text fields where shoppers may use different word forms than those found in product data.

- Enable per field using `stem: true` on any entry in `fields` or `core_field_overrides`
- Uses the [Snowball stemmer](https://snowballstem.org/)
- Only valid for string-typed fields
- Defaults to `false`

### Token Separators and Symbols to Index

These settings control how text is split into tokens during indexing and searching.

#### Token Separators

`token_separators` specifies characters that split text into separate tokens, in addition to the default whitespace splitting. This is useful for hyphenated text, part numbers, or other compound formats.

For example, with `token_separators: ["-"]`, the text `non-tech` is tokenized to `non` and `tech`, so searches for both `non-tech` and `non tech` will match.

#### Symbols to Index

`symbols_to_index` specifies special characters that should be preserved within tokens rather than stripped during indexing. Useful when products contain meaningful symbols like `+`, `#`, or `@`.

#### Collection-Level vs Field-Level

Both settings can be configured at two scopes:

- **Collection-level**: Set `token_separators` or `symbols_to_index` at the top level of the indexable fields resource to apply the setting across all indexed fields.
- **Field-level**: Set the same properties on an individual entry in `fields` or `core_field_overrides` to apply only to that field, overriding the collection-level setting.

An empty array at the field level defers to the collection-level setting.

### Reindexing Requirement

Any change to indexable fields requires reindexing your catalog releases to take effect. The system detects when indexes are out of sync. Use the [reindex endpoint](/docs/api/pxm/catalog-search/reindex-tenant-releases) to apply changes. See [Jobs](/docs/api/pxm/catalog-search/jobs) for more details on reindexing operations.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Jobs(Catalog-search)

Jobs manage the indexing operations for catalog search. When catalogs are published or when reindexing is required, jobs process the product data and build search indexes.

### Job Types

| Type                      | Description                                                                                         |
|---------------------------|-----------------------------------------------------------------------------------------------------|
| `index-release`           | Index a specific catalog release. Created automatically when a search-enabled catalog is published. |
| `delete-release`          | Remove the search index for a catalog release.                                                      |
| `reindex-tenant-releases` | Reindex all catalog releases for the store. Use when indexable fields have changed.                 |

### Job Lifecycle

Jobs progress through the following states:

1. **pending**: Job has been created and is waiting to be processed
2. **processing**: Job is actively indexing products
3. **complete**: Job finished successfully
4. **failed**: Job encountered an error

### Automatic Indexing

When you publish a catalog with search enabled, an `index-release` job is automatically created. The catalog release remains in a publishing state until the indexing job completes successfully.

### Manual Reindexing

Use the reindex endpoint when:

- You've added, modified, or deleted indexable fields
- Search indexes are out of sync (check via [Search Indexes](/docs/api/pxm/catalog-search/search-indexes))
- You need to rebuild indexes after a failure

The reindex operation creates jobs for all catalog releases that need updating. You can optionally force a full reindex of all releases regardless of their sync status.

### Conflict Handling

Only one reindexing operation can run at a time. If you attempt to start a reindex while another is in progress, the API returns a 409 Conflict error.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## List indexable fields

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List indexable fields"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/indexable-fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List indexable fields.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List indexable fields","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier of the indexable fields.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_indexable_fields`.","type":"string","example":"catalog_search_indexable_fields","enum":["catalog_search_indexable_fields"],"title":"IndexableFieldsType"},"attributes":{"type":"object","properties":{"fields":{"type":"array","x-go-type-skip-optional-pointer":true,"description":"A collection of indexable fields","title":"IndexableFields","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","description":"The name of the field.","example":"extensions.products(clothing).color","minLength":1},"type":{"type":"string","description":"The type of the field.","enum":["string","int32","int64","bool","float"],"example":"string","x-go-type":"model.FieldType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"},"title":"FieldType"},"facetable":{"type":"boolean","description":"Enables faceting on the field.","default":false,"example":true},"sortable":{"type":"boolean","description":"When set to true, the field will be sortable. Default: true for numbers, false otherwise.","example":true},"locale":{"type":"string","description":"For configuring language specific tokenization, e.g. jp for Japanese. Default: en which also broadly supports most European languages. For valid values, see [ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).","default":"en","example":"en"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Provide per-field special characters to index for this field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting.\n"}},"title":"IndexableField"},"example":[{"name":"extensions.products(clothing).color","type":"string","facetable":false,"sortable":false,"locale":"en"},{"name":"shopper_attributes.fabric","type":"string","facetable":false,"sortable":false},{"name":"admin_attributes.internal_grade","type":"string","sortable":true}]},"core_field_overrides":{"type":"array","x-go-type-skip-optional-pointer":true,"description":"Per-field configuration for core product fields (e.g. name, description).","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the core field to configure. Must be one of the supported core fields.\n","example":"name"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this core field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting. Each element must be a single character.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide per-field special characters to index for this core field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting. Each element must be a single character.\n"},"sortable":{"type":"boolean","description":"When set to true, enables sorting on this core field. Only supported for specific core fields.\n","example":true},"facetable":{"type":"boolean","description":"When set to true, enables faceting on this core field. A re-index is required for the change to take effect.\n","example":true}},"title":"CoreFieldOverride"}},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters used as token separators across the entire collection.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters indexed as part of tokens across the entire collection.\n"}},"title":"IndexableFieldsAttributes"},"meta":{"type":"object","required":["owner"],"properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"IndexableFieldsMeta"}},"title":"IndexableFields"}}},"title":"ListIndexableFieldsResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List search indexes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List search indexes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/search-indexes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List search indexes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"out_of_sync","in":"query","description":"Filter search indexes by out of sync status","required":false,"schema":{"type":"boolean"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List search indexes","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","meta"],"properties":{"id":{"description":"The unique identifier for the search index.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_index`.","type":"string","example":"catalog_search_index","enum":["catalog_search_index"],"title":"SearchIndexType"},"meta":{"type":"object","required":["catalog_id","release_id","out_of_sync","owner"],"properties":{"catalog_id":{"description":"The ID of the catalog.","type":"string","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"CatalogID"},"release_id":{"description":"The ID of the catalog release.","type":"string","example":"b2ddd253-d9bd-4344-a18b-581c1e0b25f8","x-go-name":"ReleaseID"},"out_of_sync":{"description":"Whether the search index is out of sync and needs to re-indexed.","type":"boolean","example":false},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"SearchIndexMeta"}},"title":"SearchIndex"}},"meta":{"type":"object","required":["results"],"properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","required":["total"],"properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":100}},"title":"ListResponseMetaResults"}},"title":"ListResponseMeta"}},"title":"ListSearchIndexesResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List search profiles

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List search profiles"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/search-profiles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List search profiles.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List search profiles","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the search profile.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_profile`.","type":"string","example":"catalog_search_profile","enum":["catalog_search_profile"],"title":"SearchProfileType"},"attributes":{"type":"object","required":["slug","description","fields","force_use_default_price_for_faceting_and_sorting"],"properties":{"slug":{"type":"string","description":"The unique slug of the search profile. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","example":"default","pattern":"^[a-zA-Z0-9_.-]+$","minLength":1},"description":{"type":"string","description":"The description of the search profile.","example":"Default search profile","default":""},"fields":{"type":"array","description":"A collection of search fields","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the search field.","example":"name","minLength":1},"weight":{"type":"integer","description":"The relative weight to give each field when ranking results. This can be used to boost fields in priority, when looking for matches.\nIf no explicit weights are provided for all fields, fields earlier in the fields list will be considered to have greater weight.\nIf no explicit weights are provided for some fields, the default weight of zero (0) will be used for the fields with no explicit weight.\n","example":10,"minimum":0,"maximum":15},"num_typos":{"type":"integer","description":"Per-field override for the maximum number of typographical errors [Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed\nwhen matching this field. Accepted values: 0 (exact match only), 1, or 2.\nOverrides `typo_tolerance.num_typos` for this field. Falls back to `typo_tolerance.num_typos`\nif set, otherwise default of 2.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`typo_tolerance.min_len_to_allow_single_character_correction` (default 4) and\n`typo_tolerance.min_len_to_allow_two_character_correction` (default 7):\n- A token shorter than the single-character threshold gets **no** typo correction, even with `num_typos` 1 or 2.\n- A token at least as long as the single-character threshold but shorter than the two-character threshold is corrected by **at most one** character, even with `num_typos` of 2.\n- Only tokens at least as long as the two-character threshold can use the full two corrections.\n\nFor example, with the defaults, \"appla\" → \"apple\" (length 5, one correction) is allowed,\nbut a 5-character query with two mistakes is not corrected even with `num_typos` of 2, because two-character correction requires a token of at least 7 characters.\n","minimum":0,"maximum":2,"example":1},"prefix":{"type":"boolean","description":"Per-field override for prefix (partial match) behavior on the last query token.\nWhen true, the last word is treated as a prefix; when false, it must match exactly.\nFor example, when true, a search request for \"red app\" matches \"red apple\".\nOverrides the profile-level `prefix` for this field. Falls back to the profile-level\n`prefix` if set, otherwise default of true.\n\nThe primary use case is to show results as the user is typing in the search box.\n","example":true}},"title":"SearchField"}},"text_match_type":{"type":"string","description":"When a search profile has multiple fields defined, this parameter determines how the representative text match score of a product is calculated.\n\n- `max_score (Default)`: In this mode, the products's representative score is simply the highest score from any single matching field. The field weights are used only as a tie-breaker if two products have the exact same highest score. This mode prioritizes the quality of the match in the single best-matching field.\n- `max_weight`: This mode uses the score from the matching field that has the highest weight. This means a partial, lower-quality match on a heavily weighted field (e.g., name) can be prioritized over a perfect match on a lower-weighted field (e.g., description). This mode prioritizes matches in the most important fields, regardless of match quality.\n- `sum_score`: This mode calculates a holistic score by summing the weighted scores from all matching fields. Its advantage is that it rewards products that match a query across multiple attributes. However, it carries the risk that a product with many weak, partial matches across several low-weighted fields could outrank a product with a single strong, perfect match in a high-weighted field.\n","enum":["max_score","max_weight","sum_score"],"example":"max_score","title":"TextMatchType"},"filters":{"type":"array","description":"Optional list of filter expressions to apply to search results. Multiple filters in the array are combined using OR logic (records matching filter1 || filter2 || ... filterN).\nTo combine conditions with AND logic, include multiple conditions within a single filter string (e.g., \"meta.search.categories.lvl1:=`All Products > Mens Shoes` && meta.display_price.without_tax.float_price:>100\").\nThese profile-level filters are ANDed with any filters provided in the search request via the filter_by parameter, resulting in: (profile_filter1 || profile_filter2 || ... profile_filterN) && request_filters.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"exclusions":{"type":"array","description":"A collection of exclusion expressions to apply to search results. Multiple exclusions in the array are combined using OR logic (records matching exclusion1 || exclusion2 || ... exclusionN).","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"boosts":{"type":"array","items":{"type":"object","description":"Defines a boosting rule that assigns a score to products matching a specific field value.","required":["condition","weight"],"properties":{"condition":{"type":"string","description":"A filter expression used to identify a subset of products for boosting. This follows the standard filter_by syntax.\n\nIt can be a simple condition like `meta.search.nodes.name:=\\`Electronics\\`` or complex like `meta.search.nodes.name:=\\`Electronics\\` && extensions.products(Details).brand:=Nike`.\n","minLength":1,"example":"meta.search.nodes.name:=\\`Electronics\\`"},"weight":{"type":"integer","description":"A numerical value representing the boost intensity. Products matching the criteria are assigned this value. Higher weights will cause products to appear earlier in the results.\n\n**Impact of Weights:**\n* **Boost (Positive):** Pushes products to the top.\n* **No affect (Zero):** Has no affect. Treated the same as products that match no rules.\n* **Bury (Negative):** Pushes products to the bottom.\n\n**Rule Evaluation:** The system uses \"Short-circuit\" evaluation. The engine stops at the **first matching rule**.\nThis means the weight of the first matching rule will be used as the product weight to sort the results.\nIf no rules match, the product is assigned a weight of `0`.\n","example":5}},"title":"SearchBoostRule"},"x-go-type-skip-optional-pointer":true},"prefix":{"type":"boolean","description":"Profile-level default for prefix (partial match) behavior on the last query token. When true, the last word in the query is treated as a prefix for all fields that do not have an explicit per-field prefix value. For example, a search request for \"red app\" matches \"red apple\". When false, the last word must match exactly. If omitted, default of true applies. Per-field prefix values override this setting.\nThe primary use case is to show results as the user is typing in the search box.\n","example":true},"typo_tolerance":{"type":"object","nullable":true,"description":"Optional typo tolerance configuration applied at search time.\nAll fields are optional; defaults are noted on each field.\n","properties":{"num_typos":{"type":"integer","description":"Profile-level default for the maximum number of typographical errors\n[Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed when matching any field.\nAccepted values: 0 (exact match only), 1, or 2.\nPer-field `num_typos` values override this setting. If omitted, default of 2 applies.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`min_len_to_allow_single_character_correction` (default 4) and\n`min_len_to_allow_two_character_correction` (default 7): a token shorter than the\nsingle-character threshold gets no correction at all, and a token shorter than the\ntwo-character threshold is corrected by at most one character — even when `num_typos` is 2.\nSee those two fields for details.\n","minimum":0,"maximum":2,"example":1},"min_len_to_allow_single_character_correction":{"type":"integer","description":"Minimum query-token length required before a single-character typo correction is attempted. This works together with `num_typos`: a token shorter than this length receives no typo correction at all, regardless of `num_typos`. For example, when set to 4, a search for \"appla\" will match \"apple\", but a search for \"apa\" will not match \"app\" because the length of \"apa\" is 3.\nDefault: 4.\n","minimum":1,"example":3},"min_len_to_allow_two_character_correction":{"type":"integer","description":"Minimum query-token length required before a two-character typo correction is attempted. This works together with `num_typos`: even when `num_typos` is 2, a token shorter than this length is corrected by at most one character (and a token shorter than `min_len_to_allow_single_character_correction` is not corrected at all). For example, with the default of 7, the 7-character query \"monetar\" can be corrected to \"monitor\" (two corrections), but a 6-character query with two mistakes cannot.\nDefault: 7\n","minimum":1,"example":7},"typo_tokens_threshold":{"type":"integer","description":"Typo-corrected query variations are only generated if the number of exact results\nfound is fewer than this value. Set to 0 to disable typo tolerance entirely.\nFor example, when set to 5 and the search result only has 3 results, the search engine will apply typo correction to try to return 5 or more results.\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_threshold":{"type":"integer","description":"For multi-word queries, tokens are progressively dropped if the number of results\nis fewer than this value. Set to 0 to disable token dropping.\n\nFor example, when set to 5 and the search result only has 3 results for \"red apple\" search,\nthe search engine will drop the last token \"apple\" and find more results with just by searching for \"red\".\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_mode":{"type":"string","description":"Controls the direction in which tokens are dropped from a multi-word query when\nresults fall below drop_tokens_threshold.\n- `right_to_left` (default): drops tokens from the right end of the query first.\n- `left_to_right`: drops tokens from the left end first.\n- `both_sides:N`: drops from both ends, limited to queries of N tokens or fewer\n  (e.g. `both_sides:3` applies only to queries with 3 or fewer tokens).\n","example":"right_to_left"},"enable_typos_for_numerical_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that are purely numeric (every character is a digit, e.g. \"98765\"). Such a token must then match exactly.\nDefault: true\n","example":true},"enable_typos_for_special_char_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that contain at least one non-alphanumeric character\n(any character outside `a-z`, `A-Z`, `0-9`), forcing such tokens to match exactly.\nUseful for keeping product codes / SKUs precise.\n\nTokens like `abc-123`, `abc-def`, `123-456`, and `v1.2.0` are affected;\na plain alphanumeric token like `abc123` is not.\n\nNote: the special character must be indexed on the field (via `symbols_to_index`);\notherwise the search engine removes the special characters from tokens\n(e.g. a token like v1.2.0 becomes v120) and it no longer qualifies.\n\nDefault: true\n","example":true},"split_join_tokens":{"type":"string","description":"Controls whether compound words and multi-word phrases are treated as equivalent during search.\nFor example, a query for \"nonstick\" may also match \"non stick\", and vice versa.\n- `fallback` (default): tries the original query form first; falls back to split/joined variants if results are insufficient.\n- `always`: always generates both split and joined token variants alongside the original query.\n- `off`: disables split/join token handling.\n","enum":["fallback","always","off"],"example":"fallback"}},"title":"TypoTolerance"},"synonym_settings":{"type":"object","nullable":true,"description":"Optional synonym tuning applied at search time. These settings control how synonym\nmatches are ranked and how query tokens are resolved against the synonym sets attached\nto the search profile. All fields are optional; defaults are noted on each field.\nThey only have an observable effect when synonym sets are attached to the resolved profile.\n","properties":{"demote_synonym_match":{"type":"boolean","description":"When true, results matched via a synonym are ranked below direct (non-synonym) matches. When false, synonym matches and direct matches are ranked equally.\nDefault: false\n","example":true},"synonym_resolution_allowed_on_prefix":{"type":"boolean","description":"When true, an incomplete (prefix) query token can resolve to a synonym, i.e. synonym\nexpansion is attempted on prefix tokens.\n\n**This is not the same as the `prefix` setting.** The `prefix` setting treats only the\n**last** word of the query as a prefix; `synonym_resolution_allowed_on_prefix` applies\nprefix matching at **every** token position when looking words up in the synonym sets —\nthere is no last-token special-casing.\n\n**Exact matches always win.** A query token that exactly equals a synonym key resolves\nregardless of this flag; the prefix behavior only affects the fuzzy fallback for tokens\nwith no exact synonym-key match. It composes with\n`number_of_typos_allowed_when_resolving_synonyms`, which governs typo tolerance during\nthe prefix/fuzzy lookup.\n\nWorked example (synonym keys `red`, `apple`, `apparel`):\n- `red app`: `red` matches exactly; `app` prefix-matches both `apple` and `apparel` — both expand.\n- `re app`: `re` prefix-matches `red` **and** `app` prefix-matches `apple`/`apparel` — both expand.\n  The regular `prefix` setting would only treat the last word (`app`) as a prefix; here every\n  position is prefix-matched.\n\nDefault: false\n","example":true},"number_of_typos_allowed_when_resolving_synonyms":{"type":"integer","description":"Number of typos allowed when resolving synonyms. Enables fuzzy synonym matching\nso that a misspelled query term can still trigger a synonym expansion for the\nsynonym sets attached to the search profile.\nAccepted values: 0 (exact synonym match only, default), 1, or 2.\n","minimum":0,"maximum":2,"example":0}},"title":"SynonymSettings"},"synonym_sets":{"type":"array","description":"Optional list of synonym set IDs to apply at search time. Each synonym set must exist and must have been synced to the search engine at least once. Organization-level search profiles may only reference organization-level synonym sets. Store-level search profiles may reference organization-level and same-store synonym sets.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"force_use_default_price_for_faceting_and_sorting":{"type":"boolean","description":"When set to true, the default price is used for faceting and sorting for segmented catalogs even if the catalog rule has a supported price book.","default":false,"example":true}},"title":"SearchProfileAttributes"},"meta":{"type":"object","required":["default","owner"],"properties":{"default":{"type":"boolean","description":"Whether this is the default search profile.","example":true},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"SearchProfileMeta"}},"title":"SearchProfile"}},"meta":{"type":"object","required":["results"],"properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","required":["total"],"properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":100}},"title":"ListResponseMetaResults"}},"title":"ListResponseMeta"}},"title":"ListSearchProfilesResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List searchable fields

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List searchable fields"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/searchable-fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List searchable fields.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"List searchable fields","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","description":"A collection of searchable fields.","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier of the field.","type":"string","example":"name","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_searchable_field`.","type":"string","example":"catalog_searchable_field","enum":["catalog_searchable_field"],"title":"SearchableFieldType"},"attributes":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","description":"The name of the field.","example":"name","minLength":1},"type":{"type":"string","description":"The type of the field.","enum":["string","int32","int64","bool","float"],"example":"string","x-go-type":"model.FieldType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"},"title":"FieldType"},"facetable":{"type":"boolean","description":"Enables faceting on the field.","default":false,"example":true},"sortable":{"type":"boolean","description":"When set to true, the field will be sortable. Default: true for numbers, false otherwise.","example":true},"locale":{"type":"string","description":"For configuring language specific tokenization, e.g. jp for Japanese. Default: en which also broadly supports most European languages. For valid values, see [ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).","default":"en","example":"en"}},"title":"SearchableFieldAttributes"},"meta":{"type":"object","required":["owner"],"properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"SearchableFieldMeta"}},"title":"SearchableField"}},"meta":{"type":"object","required":["results"],"properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","required":["total"],"properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":100}},"title":"ListResponseMetaResults"}},"title":"ListResponseMeta"}},"title":"SearchableFieldsResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List stopword sets

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List stopword sets"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/search/stopword-sets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all stopwords sets.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully listed stopword sets","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the stopword set.","type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_stopword_set`.","example":"catalog_search_stopword_set","enum":["catalog_search_stopword_set"],"title":"StopwordSetType"},"attributes":{"type":"object","required":["stopwords"],"properties":{"locale":{"type":"string","description":"[ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for the stopwords set. Omit or pass null for the default set. At most one stopwords set per locale is allowed.\n","example":"en"},"stopwords":{"type":"array","description":"The list of stopwords.","items":{"type":"string"},"minItems":1,"example":["the","a","an","is"]}},"title":"StopwordSetAttributes"},"meta":{"type":"object","required":["created_at","updated_at","owner","sync_status"],"properties":{"created_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was created.","example":"2026-03-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was last updated.","example":"2026-03-05T12:00:00Z"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"},"sync_status":{"type":"string","description":"The sync status of the stopword set.","enum":["pending_sync","synced","sync_failed","pending_delete"],"example":"pending_sync","x-go-type":"model.SyncStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}},"last_synced_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was last successfully synced.","example":"2026-03-05T12:01:00Z"}},"title":"StopwordSetMeta"}},"title":"StopwordSet"}},"meta":{"type":"object","required":["results"],"properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","required":["total"],"properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":100}},"title":"ListResponseMetaResults"}},"title":"ListResponseMeta"}},"title":"ListStopwordSetsResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List synonym sets

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List synonym sets"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/search/synonym-sets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all synonym sets.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully listed synonym sets","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the synonym set.","type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_synonym_set`.","example":"catalog_search_synonym_set","enum":["catalog_search_synonym_set"],"title":"SynonymSetType"},"attributes":{"type":"object","required":["name","items"],"properties":{"name":{"type":"string","description":"Human-readable name for the synonym set.","example":"Apparel terms"},"items":{"type":"array","description":"The synonym items in this set.","items":{"type":"object","required":["id","synonyms"],"properties":{"id":{"type":"string","description":"Unique identifier for the synonym item within the set. Alphanumeric, hyphen, and underscore only.","pattern":"^[a-zA-Z0-9_-]+$","example":"footwear-terms","x-go-name":"ID"},"synonyms":{"type":"array","description":"List of synonym terms.","items":{"type":"string"},"minItems":1,"example":["sneakers","trainers","running shoes"]},"root":{"type":"string","description":"Makes this a one-way synonym. Searches for root also match synonyms, but not vice versa.","example":"jacket"},"locale":{"type":"string","description":"[ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for this synonym item.\n","example":"en"},"symbols_to_index":{"type":"array","description":"Symbols to index for this synonym item. Each element must be exactly one character.","items":{"type":"string","minLength":1,"maxLength":1},"example":["-"],"x-go-type-skip-optional-pointer":true}},"title":"SynonymSetItem"},"minItems":1}},"title":"SynonymSetAttributes"},"meta":{"type":"object","required":["created_at","updated_at","owner","sync_status"],"properties":{"created_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was created.","example":"2026-03-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was last updated.","example":"2026-03-05T12:00:00Z"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"},"sync_status":{"type":"string","description":"The sync status of the synonym set.","enum":["pending_sync","synced","sync_failed","pending_delete"],"example":"pending_sync","x-go-type":"model.SyncStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}},"last_synced_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was last successfully synced.","example":"2026-03-05T12:01:00Z"}},"title":"SynonymSetMeta"}},"title":"SynonymSet"}},"meta":{"type":"object","required":["results"],"properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","required":["total"],"properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":100}},"title":"ListResponseMetaResults"}},"title":"ListResponseMeta"}},"title":"ListSynonymSetsResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Admin Multi-search

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Admin Multi-search"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/catalogs/{catalog_id}/releases/{release_id}/multi-search"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Execute one or more searches in a single request.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the catalog to query","x-go-name":"catalogID"},{"name":"release_id","in":"path","required":true,"schema":{"type":"string"},"description":"The unique ID of a published release of the catalog or `latestPublished` for the most recently published version","x-go-name":"releaseID"},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","schema":{"type":"string"},"example":"en-US","required":false},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]},"example":["main_image","component_products"]}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","schema":{"type":"array","maxItems":5,"items":{"type":"string"}}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","schema":{"type":"array","maxItems":5,"items":{"type":"string"}}},{"in":"query","name":"search_profile","description":"The slug of the search profile to use for this search. Do not specify to use default search profile.","schema":{"type":"string","pattern":"^[a-zA-Z0-9_.-]+$"},"example":"clothing","x-go-name":"SearchProfileSlug"},{"in":"header","name":"EP-Simulated-Shopper-Date","schema":{"type":"string"},"required":false}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["searches"],"properties":{"searches":{"type":"array","minItems":1,"items":{"type":"object","properties":{"type":{"type":"string","enum":["search","autocomplete"],"example":"search","description":"Type of search operation to perform"},"highlight_full_fields":{"type":"string","example":"name,description"},"q":{"type":"string","example":"search query"},"facet_by":{"type":"string","description":"Specifies which fields to use for generating facets in search results. See [faceting](/guides/How-To/Catalogs/Search/faceting) for more details.","example":"meta.search.nodes.name","title":"FacetByField"},"filter_by":{"type":"string","description":"Applies conditions to narrow down search results based on specific field values. See [filtering](/guides/How-To/Catalogs/Search/filtering) for more details.","example":"meta.search.nodes.name:=Electronics && price.float_price:>=10.00","title":"FilterByField"},"sort_by":{"type":"string","description":"Orders search results by specified fields. See [sorting](/guides/How-To/Catalogs/Search/sorting) for more details.","example":"price.amount:asc,extensions.products(Specification).rating:desc","title":"SortByField"},"max_facet_values":{"type":"integer","example":10},"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":20}},"title":"SearchQuery"}}},"title":"MultiSearchRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Multi-search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["search","autocomplete"],"example":"search","description":"Type of search operation to performed","title":"SearchResultType"},"facet_counts":{"type":"array","items":{"type":"object","properties":{"counts":{"type":"array","items":{"type":"object","properties":{"count":{"type":"integer","example":42},"highlighted":{"type":"string","example":"electronics"},"value":{"type":"string","example":"electronics"}},"title":"FacetValue"}},"field_name":{"type":"string","example":"category"},"sampled":{"type":"boolean","example":false},"stats":{"type":"object"}},"title":"FacetCount"}},"found":{"type":"integer","example":150},"hits":{"type":"array","items":{"type":"object","properties":{"document":{"oneOf":[{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","description":"Arbitrary document object"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","description":"Arbitrary document object"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","description":"Arbitrary document object"}}},{"type":"object","title":"AutocompleteResponse","description":"An autocomplete suggestion with query frequency information.","properties":{"id":{"description":"A unique identifier for the autocomplete suggestion.","type":"string","example":"hammer_123","x-go-name":"ID"},"q":{"description":"The query text for the autocomplete suggestion.","type":"string","example":"hammer","x-go-name":"Query"},"count":{"description":"The frequency count of this query.","type":"integer","example":42,"x-go-name":"Count"}}}],"description":"Document object - either a Product or AutocompleteResponse"},"highlight":{"type":"object"},"highlights":{"type":"array","items":{"type":"object"}},"text_match_info":{"allOf":[{"type":"object","description":"Breakdown of how the text relevance score for this hit was derived. Values are copied unchanged from the underlying search engine response.\n\nThese are **internal ranking signals** for debugging relevance and tuning Search Profiles — not user-facing match percentages. Scores are not normalized to a 0–100 scale. Higher `score` values indicate greater relevance **within the same search result set**; scores are not comparable across different queries.\n\nThe overall relevance integer is available as `score` (string). Catalog Search does not expose the search engine's separate top-level `text_match` field.\n\n**Good uses:** debugging why one product ranks above another; building custom relative metrics (e.g. `tokens_matched` vs query length); merchandising and relevance tuning.\n\n**Poor uses:** displaying \"match %\" to shoppers; filtering by absolute thresholds without per-query calibration; comparing scores across unrelated searches.\n\nHow the final `score` is aggregated depends on the active Search Profile's `text_match_type`:\n- `max_score` (default): best field score wins; weights break ties\n- `max_weight`: highest-weighted matching field drives the score\n- `sum_score`: weighted field scores are summed\n","properties":{"best_field_score":{"type":"string","description":"Raw text match score of the single best-performing field in the Search Profile's `query_by` list.\nA large opaque integer — field-level, not normalized. In `max_score` mode (default), this is the strongest per-field signal driving the document score.\n","example":"2211897868289"},"best_field_weight":{"type":"integer","description":"The `query_by_weights` value of the best-matching field (0–127). For example, `15` indicates the winning match came from a high-priority profile field such as `meta.search.nodes.name`.\nUnder `max_score`, weight is mainly a tie-breaker when two documents share the same field score. Under `max_weight`, it determines which field's score represents the document.\n","example":15},"fields_matched":{"type":"integer","description":"Number of `query_by` fields that contained at least one query token. May differ from the number of highlighted fields — highlighting scans all queried fields for display, while scoring weights fields differently.\n","example":2},"num_tokens_dropped":{"type":"integer","format":"int64","description":"Number of query tokens not matched in this document (`max(0, total_query_tokens − tokens_matched)`). `0` means full query coverage; `1` means one token was missing (e.g. searching \"Blue Vase Ceramic\" but the document only matches \"Blue Vase\").\nReports token coverage for this specific hit, not the global `drop_tokens_threshold` query-relaxation behaviour.\n","example":0},"score":{"type":"string","description":"String form of the packed 64-bit text relevance score used to rank this hit. Equivalent to the search engine's `text_match` integer — use this field for the overall relevance value. Higher means more relevant within the current result set.\n","example":"1157451471441102970"},"tokens_matched":{"type":"integer","description":"Number of distinct query words found in the document. Each query token is counted at most once per document, even if it appears multiple times in the text. Highlighting may show repeated occurrences; this count will not.\n","example":2},"typo_prefix_score":{"type":"integer","description":"Diagnostic signal indicating how much prefix matching or typo correction contributed to the match. `0` typically indicates an exact token match with no fuzzy or prefix-based relaxation; higher values may appear when `num_typos` or `prefix` matching was involved. Not a directly configurable parameter — treat as a tuning/debugging signal, not a display metric.\n","example":0}},"title":"TextMatchInfo"}],"description":"Relevance metadata for this hit, included when the search engine returns it. Omitted when relevance metadata is unavailable (e.g. some autocomplete results).\nHit order in the response reflects ranking driven by these scores.\n"}},"title":"Hit"}},"out_of":{"type":"integer","example":150},"page":{"type":"integer","example":1},"request_params":{"type":"object"},"search_cutoff":{"type":"boolean","example":false},"search_time_ms":{"type":"integer","example":25}},"title":"SearchResult"}},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","additionalProperties":{"type":"array","items":{"type":"object"}},"title":"IncludedResponse"}},"title":"MultiSearchResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"invalid-filter":{"value":{"errors":[{"title":"Invalid Filter","status":"400","detail":"Could not parse the filter query."}]}},"invalid-facet":{"value":{"errors":[{"title":"Invalid Facet","status":"400","detail":"Invalid facet field specified."}]}},"invalid-pagination":{"value":{"errors":[{"title":"Invalid Pagination","status":"400","detail":"Invalid page or per_page parameter."}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Multi-search

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Multi-search"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/catalog/multi-search"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Execute one or more searches in a single request.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","schema":{"type":"string"},"example":"en-US","required":false},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","schema":{"type":"string"},"required":false},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]},"example":["main_image","component_products"]}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","schema":{"type":"string"},"required":false},{"in":"query","name":"search_profile","description":"The slug of the search profile to use for this search. Do not specify to use default search profile.","schema":{"type":"string","pattern":"^[a-zA-Z0-9_.-]+$"},"example":"clothing","x-go-name":"SearchProfileSlug"},{"in":"header","name":"EP-Simulated-Shopper-Date","schema":{"type":"string"},"required":false}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["searches"],"properties":{"searches":{"type":"array","minItems":1,"items":{"type":"object","properties":{"type":{"type":"string","enum":["search","autocomplete"],"example":"search","description":"Type of search operation to perform"},"highlight_full_fields":{"type":"string","example":"name,description"},"q":{"type":"string","example":"search query"},"facet_by":{"type":"string","description":"Specifies which fields to use for generating facets in search results. See [faceting](/guides/How-To/Catalogs/Search/faceting) for more details.","example":"meta.search.nodes.name","title":"FacetByField"},"filter_by":{"type":"string","description":"Applies conditions to narrow down search results based on specific field values. See [filtering](/guides/How-To/Catalogs/Search/filtering) for more details.","example":"meta.search.nodes.name:=Electronics && price.float_price:>=10.00","title":"FilterByField"},"sort_by":{"type":"string","description":"Orders search results by specified fields. See [sorting](/guides/How-To/Catalogs/Search/sorting) for more details.","example":"price.amount:asc,extensions.products(Specification).rating:desc","title":"SortByField"},"max_facet_values":{"type":"integer","example":10},"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":20}},"title":"SearchQuery"}}},"title":"MultiSearchRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Multi-search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["search","autocomplete"],"example":"search","description":"Type of search operation to performed","title":"SearchResultType"},"facet_counts":{"type":"array","items":{"type":"object","properties":{"counts":{"type":"array","items":{"type":"object","properties":{"count":{"type":"integer","example":42},"highlighted":{"type":"string","example":"electronics"},"value":{"type":"string","example":"electronics"}},"title":"FacetValue"}},"field_name":{"type":"string","example":"category"},"sampled":{"type":"boolean","example":false},"stats":{"type":"object"}},"title":"FacetCount"}},"found":{"type":"integer","example":150},"hits":{"type":"array","items":{"type":"object","properties":{"document":{"oneOf":[{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","description":"Arbitrary document object"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","description":"Arbitrary document object"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","description":"Arbitrary document object"}}},{"type":"object","title":"AutocompleteResponse","description":"An autocomplete suggestion with query frequency information.","properties":{"id":{"description":"A unique identifier for the autocomplete suggestion.","type":"string","example":"hammer_123","x-go-name":"ID"},"q":{"description":"The query text for the autocomplete suggestion.","type":"string","example":"hammer","x-go-name":"Query"},"count":{"description":"The frequency count of this query.","type":"integer","example":42,"x-go-name":"Count"}}}],"description":"Document object - either a Product or AutocompleteResponse"},"highlight":{"type":"object"},"highlights":{"type":"array","items":{"type":"object"}},"text_match_info":{"allOf":[{"type":"object","description":"Breakdown of how the text relevance score for this hit was derived. Values are copied unchanged from the underlying search engine response.\n\nThese are **internal ranking signals** for debugging relevance and tuning Search Profiles — not user-facing match percentages. Scores are not normalized to a 0–100 scale. Higher `score` values indicate greater relevance **within the same search result set**; scores are not comparable across different queries.\n\nThe overall relevance integer is available as `score` (string). Catalog Search does not expose the search engine's separate top-level `text_match` field.\n\n**Good uses:** debugging why one product ranks above another; building custom relative metrics (e.g. `tokens_matched` vs query length); merchandising and relevance tuning.\n\n**Poor uses:** displaying \"match %\" to shoppers; filtering by absolute thresholds without per-query calibration; comparing scores across unrelated searches.\n\nHow the final `score` is aggregated depends on the active Search Profile's `text_match_type`:\n- `max_score` (default): best field score wins; weights break ties\n- `max_weight`: highest-weighted matching field drives the score\n- `sum_score`: weighted field scores are summed\n","properties":{"best_field_score":{"type":"string","description":"Raw text match score of the single best-performing field in the Search Profile's `query_by` list.\nA large opaque integer — field-level, not normalized. In `max_score` mode (default), this is the strongest per-field signal driving the document score.\n","example":"2211897868289"},"best_field_weight":{"type":"integer","description":"The `query_by_weights` value of the best-matching field (0–127). For example, `15` indicates the winning match came from a high-priority profile field such as `meta.search.nodes.name`.\nUnder `max_score`, weight is mainly a tie-breaker when two documents share the same field score. Under `max_weight`, it determines which field's score represents the document.\n","example":15},"fields_matched":{"type":"integer","description":"Number of `query_by` fields that contained at least one query token. May differ from the number of highlighted fields — highlighting scans all queried fields for display, while scoring weights fields differently.\n","example":2},"num_tokens_dropped":{"type":"integer","format":"int64","description":"Number of query tokens not matched in this document (`max(0, total_query_tokens − tokens_matched)`). `0` means full query coverage; `1` means one token was missing (e.g. searching \"Blue Vase Ceramic\" but the document only matches \"Blue Vase\").\nReports token coverage for this specific hit, not the global `drop_tokens_threshold` query-relaxation behaviour.\n","example":0},"score":{"type":"string","description":"String form of the packed 64-bit text relevance score used to rank this hit. Equivalent to the search engine's `text_match` integer — use this field for the overall relevance value. Higher means more relevant within the current result set.\n","example":"1157451471441102970"},"tokens_matched":{"type":"integer","description":"Number of distinct query words found in the document. Each query token is counted at most once per document, even if it appears multiple times in the text. Highlighting may show repeated occurrences; this count will not.\n","example":2},"typo_prefix_score":{"type":"integer","description":"Diagnostic signal indicating how much prefix matching or typo correction contributed to the match. `0` typically indicates an exact token match with no fuzzy or prefix-based relaxation; higher values may appear when `num_typos` or `prefix` matching was involved. Not a directly configurable parameter — treat as a tuning/debugging signal, not a display metric.\n","example":0}},"title":"TextMatchInfo"}],"description":"Relevance metadata for this hit, included when the search engine returns it. Omitted when relevance metadata is unavailable (e.g. some autocomplete results).\nHit order in the response reflects ranking driven by these scores.\n"}},"title":"Hit"}},"out_of":{"type":"integer","example":150},"page":{"type":"integer","example":1},"request_params":{"type":"object"},"search_cutoff":{"type":"boolean","example":false},"search_time_ms":{"type":"integer","example":25}},"title":"SearchResult"}},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","additionalProperties":{"type":"array","items":{"type":"object"}},"title":"IncludedResponse"}},"title":"MultiSearchResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"invalid-filter":{"value":{"errors":[{"title":"Invalid Filter","status":"400","detail":"Could not parse the filter query."}]}},"invalid-facet":{"value":{"errors":[{"title":"Invalid Facet","status":"400","detail":"Invalid facet field specified."}]}},"invalid-pagination":{"value":{"errors":[{"title":"Invalid Pagination","status":"400","detail":"Invalid page or per_page parameter."}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Reindex all releases for tenant

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Reindex all releases for tenant"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/catalogs/reindex-releases"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new job to reindex all releases for the tenant.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"The primary data for the request.","type":"object","properties":{"force_reindex":{"description":"Reindex all releases for tenant whether the release index is out of sync or not.","type":"boolean","default":false,"example":true,"x-go-type-skip-optional-pointer":true}}}},"title":"ReindexTenantReleasesJobRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Reindex tenant releases request successful","content":{"application/json":{"schema":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"description":"The unique identifier for the job.","type":"string","format":"uuid","example":"4c9efe34-57bb-4117-abed-184008d3ae0a","x-go-name":"ID"},"type":{"description":"The type of the resource object.","type":"string","enum":["job"],"example":"job"},"attributes":{"description":"The attributes of the job.","type":"object","required":["status","type"],"properties":{"status":{"description":"The status of the job.","type":"string","enum":["pending","processing","complete","failed"],"example":"pending"},"catalog_id":{"description":"The ID of the catalog.","type":"string","format":"uuid","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"CatalogID"},"catalog_release_id":{"description":"The ID of the catalog release.","type":"string","format":"uuid","example":"c12c4e5b-f5e4-4bd0-ac86-9f1202fc27f9","x-go-name":"CatalogReleaseID"},"type":{"description":"The type of the job.","type":"string","enum":["index-release","delete-release","reindex-tenant-releases"],"example":"index-release","default":"index","x-go-type":"model.JobType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}}},"title":"JobAttributes"},"meta":{"description":"Meta information of the job","type":"object","properties":{"results":{"description":"Results of the job","type":"array","items":{"description":"Result of the job","type":"object","title":"JobMetaResult"}},"errors":{"description":"Errors occurred during the job","type":"array","items":{"type":"object","required":["detail"],"properties":{"detail":{"description":"A string describing the error.","type":"string","example":"Failed to get release"},"context":{"description":"Any additional context of the error.","type":"object"}},"title":"JobMetaError"}}},"title":"JobMeta"}},"title":"Job"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"409":{"description":"Conflict - another reindexing job already queued or in progress","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Admin Search

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Admin Search"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalogs/{catalog_id}/releases/{release_id}/search"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Execute search.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"},"description":"The ID of the catalog to query","x-go-name":"catalogID"},{"name":"release_id","in":"path","required":true,"schema":{"type":"string"},"description":"The unique ID of a published release of the catalog or `latestPublished` for the most recently published version","x-go-name":"releaseID"},{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","schema":{"type":"string"},"example":"en-US","required":false},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]},"example":["main_image","component_products"]}},{"in":"header","name":"EP-Pricebook-IDs-For-Price-Segmentation-Preview","description":"Supply a comma delimited list of pricebook ids to be used to lookup product prices from when the catalog supports price segmentation. The first pricebook will be highest priority (if more than one is supplied) and the rest in descending priority order. Used only for admin endpoints that dont support shopper context lookup.","schema":{"type":"array","maxItems":5,"items":{"type":"string"}}},{"in":"header","name":"EP-Pricebook-IDs-Of-Available-Prices-To-Show","description":"Supply a comma delimited list of pricebook ids to be listed in meta sections available prices . 'all' is a permitted value and will ensure all available prices for a product are shown. 'all' is not recommended if there are lots(10+) of available prices due the large response size.","schema":{"type":"array","maxItems":5,"items":{"type":"string"}}},{"in":"query","name":"search_profile","description":"The slug of the search profile to use for this search. Do not specify to use default search profile.","schema":{"type":"string","pattern":"^[a-zA-Z0-9_.-]+$"},"example":"clothing","x-go-name":"SearchProfileSlug"},{"in":"query","name":"type","description":"Type of search operation to perform","schema":{"type":"string","enum":["search","autocomplete"]},"example":"search"},{"in":"query","name":"highlight_full_fields","description":"Comma-separated list of fields to highlight","schema":{"type":"string"},"example":"name,description"},{"in":"query","name":"q","description":"Search query","schema":{"type":"string"},"required":true,"example":"search query"},{"in":"query","name":"facet_by","description":"Specifies which fields to use for generating facets in search results. See [faceting](/guides/How-To/Catalogs/Search/faceting) for more details.","example":"meta.search.nodes.name","schema":{"type":"string"}},{"in":"query","name":"filter_by","description":"Applies conditions to narrow down search results based on specific field values. See [filtering](/guides/How-To/Catalogs/Search/filtering) for more details.","example":"meta.search.nodes.name:=Electronics && price.float_price:>=10.00","schema":{"type":"string"}},{"in":"query","name":"sort_by","description":"Orders search results by specified fields. See [sorting](/guides/How-To/Catalogs/Search/sorting) for more details.","example":"price.amount:asc,extensions.products(Specification).rating:desc","schema":{"type":"string"}},{"in":"query","name":"max_facet_values","description":"Maximum number of facet values to return","schema":{"type":"integer"},"example":10},{"in":"header","name":"EP-Simulated-Shopper-Date","schema":{"type":"string"},"required":false},{"in":"query","name":"page","schema":{"type":"integer"},"example":1},{"in":"query","name":"per_page","schema":{"type":"integer"},"example":10}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Search results","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["search","autocomplete"],"example":"search","description":"Type of search operation to performed","title":"SearchResultType"},"facet_counts":{"type":"array","items":{"type":"object","properties":{"counts":{"type":"array","items":{"type":"object","properties":{"count":{"type":"integer","example":42},"highlighted":{"type":"string","example":"electronics"},"value":{"type":"string","example":"electronics"}},"title":"FacetValue"}},"field_name":{"type":"string","example":"category"},"sampled":{"type":"boolean","example":false},"stats":{"type":"object"}},"title":"FacetCount"}},"found":{"type":"integer","example":150},"hits":{"type":"array","items":{"type":"object","properties":{"document":{"oneOf":[{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","description":"Arbitrary document object"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","description":"Arbitrary document object"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","description":"Arbitrary document object"}}},{"type":"object","title":"AutocompleteResponse","description":"An autocomplete suggestion with query frequency information.","properties":{"id":{"description":"A unique identifier for the autocomplete suggestion.","type":"string","example":"hammer_123","x-go-name":"ID"},"q":{"description":"The query text for the autocomplete suggestion.","type":"string","example":"hammer","x-go-name":"Query"},"count":{"description":"The frequency count of this query.","type":"integer","example":42,"x-go-name":"Count"}}}],"description":"Document object - either a Product or AutocompleteResponse"},"highlight":{"type":"object"},"highlights":{"type":"array","items":{"type":"object"}},"text_match_info":{"allOf":[{"type":"object","description":"Breakdown of how the text relevance score for this hit was derived. Values are copied unchanged from the underlying search engine response.\n\nThese are **internal ranking signals** for debugging relevance and tuning Search Profiles — not user-facing match percentages. Scores are not normalized to a 0–100 scale. Higher `score` values indicate greater relevance **within the same search result set**; scores are not comparable across different queries.\n\nThe overall relevance integer is available as `score` (string). Catalog Search does not expose the search engine's separate top-level `text_match` field.\n\n**Good uses:** debugging why one product ranks above another; building custom relative metrics (e.g. `tokens_matched` vs query length); merchandising and relevance tuning.\n\n**Poor uses:** displaying \"match %\" to shoppers; filtering by absolute thresholds without per-query calibration; comparing scores across unrelated searches.\n\nHow the final `score` is aggregated depends on the active Search Profile's `text_match_type`:\n- `max_score` (default): best field score wins; weights break ties\n- `max_weight`: highest-weighted matching field drives the score\n- `sum_score`: weighted field scores are summed\n","properties":{"best_field_score":{"type":"string","description":"Raw text match score of the single best-performing field in the Search Profile's `query_by` list.\nA large opaque integer — field-level, not normalized. In `max_score` mode (default), this is the strongest per-field signal driving the document score.\n","example":"2211897868289"},"best_field_weight":{"type":"integer","description":"The `query_by_weights` value of the best-matching field (0–127). For example, `15` indicates the winning match came from a high-priority profile field such as `meta.search.nodes.name`.\nUnder `max_score`, weight is mainly a tie-breaker when two documents share the same field score. Under `max_weight`, it determines which field's score represents the document.\n","example":15},"fields_matched":{"type":"integer","description":"Number of `query_by` fields that contained at least one query token. May differ from the number of highlighted fields — highlighting scans all queried fields for display, while scoring weights fields differently.\n","example":2},"num_tokens_dropped":{"type":"integer","format":"int64","description":"Number of query tokens not matched in this document (`max(0, total_query_tokens − tokens_matched)`). `0` means full query coverage; `1` means one token was missing (e.g. searching \"Blue Vase Ceramic\" but the document only matches \"Blue Vase\").\nReports token coverage for this specific hit, not the global `drop_tokens_threshold` query-relaxation behaviour.\n","example":0},"score":{"type":"string","description":"String form of the packed 64-bit text relevance score used to rank this hit. Equivalent to the search engine's `text_match` integer — use this field for the overall relevance value. Higher means more relevant within the current result set.\n","example":"1157451471441102970"},"tokens_matched":{"type":"integer","description":"Number of distinct query words found in the document. Each query token is counted at most once per document, even if it appears multiple times in the text. Highlighting may show repeated occurrences; this count will not.\n","example":2},"typo_prefix_score":{"type":"integer","description":"Diagnostic signal indicating how much prefix matching or typo correction contributed to the match. `0` typically indicates an exact token match with no fuzzy or prefix-based relaxation; higher values may appear when `num_typos` or `prefix` matching was involved. Not a directly configurable parameter — treat as a tuning/debugging signal, not a display metric.\n","example":0}},"title":"TextMatchInfo"}],"description":"Relevance metadata for this hit, included when the search engine returns it. Omitted when relevance metadata is unavailable (e.g. some autocomplete results).\nHit order in the response reflects ranking driven by these scores.\n"}},"title":"Hit"}},"out_of":{"type":"integer","example":150},"page":{"type":"integer","example":1},"request_params":{"type":"object"},"search_cutoff":{"type":"boolean","example":false},"search_time_ms":{"type":"integer","example":25}},"title":"SearchResult"},{"type":"object","properties":{"included":{"type":"object","description":"Included is an array of resources that are included in the response.","additionalProperties":{"type":"array","items":{"type":"object"}},"title":"IncludedResponse"}}}],"title":"SearchResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"invalid-filter":{"value":{"errors":[{"title":"Invalid Filter","status":"400","detail":"Could not parse the filter query."}]}},"invalid-facet":{"value":{"errors":[{"title":"Invalid Facet","status":"400","detail":"Invalid facet field specified."}]}},"invalid-pagination":{"value":{"errors":[{"title":"Invalid Pagination","status":"400","detail":"Invalid page or per_page parameter."}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Search

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/catalog/search"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Execute search.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"The language and locale your storefront prefers. See [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).","in":"header","name":"accept-language","schema":{"type":"string"},"example":"en-US","required":false},{"description":"The list of channels in which this catalog can be displayed. A channel is the shopping experience, such as a mobile app or web storefront. If empty, the catalog rule matches all channels. The channel will eventually be included in the bearer token that is used for authorization, but currently, you must set the `EP-Channel` header in your requests.","in":"header","name":"EP-Channel","schema":{"type":"string"},"required":false},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["files","main_image","component_products"]},"example":["main_image","component_products"]}},{"description":"Tags are used to refine the eligibility criteria for a rule. Requests populate the catalog rule tag using the `EP-Context-Tag` header.","in":"header","name":"EP-Context-Tag","schema":{"type":"string"},"required":false},{"in":"query","name":"search_profile","description":"The slug of the search profile to use for this search. Do not specify to use default search profile.","schema":{"type":"string","pattern":"^[a-zA-Z0-9_.-]+$"},"example":"clothing","x-go-name":"SearchProfileSlug"},{"in":"query","name":"type","description":"Type of search operation to perform","schema":{"type":"string","enum":["search","autocomplete"]},"example":"search"},{"in":"query","name":"highlight_full_fields","description":"Comma-separated list of fields to highlight","schema":{"type":"string"},"example":"name,description"},{"in":"query","name":"q","description":"Search query","schema":{"type":"string"},"required":true,"example":"search query"},{"in":"query","name":"facet_by","description":"Specifies which fields to use for generating facets in search results. See [faceting](/guides/How-To/Catalogs/Search/faceting) for more details.","example":"meta.search.nodes.name","schema":{"type":"string"}},{"in":"query","name":"filter_by","description":"Applies conditions to narrow down search results based on specific field values. See [filtering](/guides/How-To/Catalogs/Search/filtering) for more details.","example":"meta.search.nodes.name:=Electronics && price.float_price:>=10.00","schema":{"type":"string"}},{"in":"query","name":"sort_by","description":"Orders search results by specified fields. See [sorting](/guides/How-To/Catalogs/Search/sorting) for more details.","example":"price.amount:asc,extensions.products(Specification).rating:desc","schema":{"type":"string"}},{"in":"query","name":"max_facet_values","description":"Maximum number of facet values to return","schema":{"type":"integer"},"example":10},{"in":"header","name":"EP-Simulated-Shopper-Date","schema":{"type":"string"},"required":false},{"in":"query","name":"page","schema":{"type":"integer"},"example":1},{"in":"query","name":"per_page","schema":{"type":"integer"},"example":10}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Search results","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"type":{"type":"string","enum":["search","autocomplete"],"example":"search","description":"Type of search operation to performed","title":"SearchResultType"},"facet_counts":{"type":"array","items":{"type":"object","properties":{"counts":{"type":"array","items":{"type":"object","properties":{"count":{"type":"integer","example":42},"highlighted":{"type":"string","example":"electronics"},"value":{"type":"string","example":"electronics"}},"title":"FacetValue"}},"field_name":{"type":"string","example":"category"},"sampled":{"type":"boolean","example":false},"stats":{"type":"object"}},"title":"FacetCount"}},"found":{"type":"integer","example":150},"hits":{"type":"array","items":{"type":"object","properties":{"document":{"oneOf":[{"type":"object","title":"Product","description":"A product in a catalog with the following attributes.","properties":{"attributes":{"type":"object","description":"Arbitrary document object"},"id":{"description":"A unique identifier for a product.","type":"string","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"relationships":{"type":"object","description":"Arbitrary document object"},"type":{"description":"This represents the type of object being returned. Always `product`.","type":"string","example":"product","x-go-name":"Type"},"meta":{"type":"object","description":"Arbitrary document object"}}},{"type":"object","title":"AutocompleteResponse","description":"An autocomplete suggestion with query frequency information.","properties":{"id":{"description":"A unique identifier for the autocomplete suggestion.","type":"string","example":"hammer_123","x-go-name":"ID"},"q":{"description":"The query text for the autocomplete suggestion.","type":"string","example":"hammer","x-go-name":"Query"},"count":{"description":"The frequency count of this query.","type":"integer","example":42,"x-go-name":"Count"}}}],"description":"Document object - either a Product or AutocompleteResponse"},"highlight":{"type":"object"},"highlights":{"type":"array","items":{"type":"object"}},"text_match_info":{"allOf":[{"type":"object","description":"Breakdown of how the text relevance score for this hit was derived. Values are copied unchanged from the underlying search engine response.\n\nThese are **internal ranking signals** for debugging relevance and tuning Search Profiles — not user-facing match percentages. Scores are not normalized to a 0–100 scale. Higher `score` values indicate greater relevance **within the same search result set**; scores are not comparable across different queries.\n\nThe overall relevance integer is available as `score` (string). Catalog Search does not expose the search engine's separate top-level `text_match` field.\n\n**Good uses:** debugging why one product ranks above another; building custom relative metrics (e.g. `tokens_matched` vs query length); merchandising and relevance tuning.\n\n**Poor uses:** displaying \"match %\" to shoppers; filtering by absolute thresholds without per-query calibration; comparing scores across unrelated searches.\n\nHow the final `score` is aggregated depends on the active Search Profile's `text_match_type`:\n- `max_score` (default): best field score wins; weights break ties\n- `max_weight`: highest-weighted matching field drives the score\n- `sum_score`: weighted field scores are summed\n","properties":{"best_field_score":{"type":"string","description":"Raw text match score of the single best-performing field in the Search Profile's `query_by` list.\nA large opaque integer — field-level, not normalized. In `max_score` mode (default), this is the strongest per-field signal driving the document score.\n","example":"2211897868289"},"best_field_weight":{"type":"integer","description":"The `query_by_weights` value of the best-matching field (0–127). For example, `15` indicates the winning match came from a high-priority profile field such as `meta.search.nodes.name`.\nUnder `max_score`, weight is mainly a tie-breaker when two documents share the same field score. Under `max_weight`, it determines which field's score represents the document.\n","example":15},"fields_matched":{"type":"integer","description":"Number of `query_by` fields that contained at least one query token. May differ from the number of highlighted fields — highlighting scans all queried fields for display, while scoring weights fields differently.\n","example":2},"num_tokens_dropped":{"type":"integer","format":"int64","description":"Number of query tokens not matched in this document (`max(0, total_query_tokens − tokens_matched)`). `0` means full query coverage; `1` means one token was missing (e.g. searching \"Blue Vase Ceramic\" but the document only matches \"Blue Vase\").\nReports token coverage for this specific hit, not the global `drop_tokens_threshold` query-relaxation behaviour.\n","example":0},"score":{"type":"string","description":"String form of the packed 64-bit text relevance score used to rank this hit. Equivalent to the search engine's `text_match` integer — use this field for the overall relevance value. Higher means more relevant within the current result set.\n","example":"1157451471441102970"},"tokens_matched":{"type":"integer","description":"Number of distinct query words found in the document. Each query token is counted at most once per document, even if it appears multiple times in the text. Highlighting may show repeated occurrences; this count will not.\n","example":2},"typo_prefix_score":{"type":"integer","description":"Diagnostic signal indicating how much prefix matching or typo correction contributed to the match. `0` typically indicates an exact token match with no fuzzy or prefix-based relaxation; higher values may appear when `num_typos` or `prefix` matching was involved. Not a directly configurable parameter — treat as a tuning/debugging signal, not a display metric.\n","example":0}},"title":"TextMatchInfo"}],"description":"Relevance metadata for this hit, included when the search engine returns it. Omitted when relevance metadata is unavailable (e.g. some autocomplete results).\nHit order in the response reflects ranking driven by these scores.\n"}},"title":"Hit"}},"out_of":{"type":"integer","example":150},"page":{"type":"integer","example":1},"request_params":{"type":"object"},"search_cutoff":{"type":"boolean","example":false},"search_time_ms":{"type":"integer","example":25}},"title":"SearchResult"},{"type":"object","properties":{"included":{"type":"object","description":"Included is an array of resources that are included in the response.","additionalProperties":{"type":"array","items":{"type":"object"}},"title":"IncludedResponse"}}}],"title":"SearchResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"invalid-filter":{"value":{"errors":[{"title":"Invalid Filter","status":"400","detail":"Could not parse the filter query."}]}},"invalid-facet":{"value":{"errors":[{"title":"Invalid Facet","status":"400","detail":"Invalid facet field specified."}]}},"invalid-pagination":{"value":{"errors":[{"title":"Invalid Pagination","status":"400","detail":"Invalid page or per_page parameter."}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Search Indexes

Search Indexes represent the indexed data for your catalog releases. Each time a catalog is published with search enabled, a search index is created containing the product data optimized for fast querying.

### Index Status

The Search Indexes API allows you to view the status of your indexes and identify any that are out of sync. An index becomes out of sync when:

- Indexable fields have been added, modified, or deleted
- The index failed to build during catalog publishing
- A reindex is required due to schema changes

### Monitoring Indexes

Use the list endpoint to:

- **View all indexes**: See all search indexes for your store
- **Check sync status**: Identify indexes that need reindexing
- **Filter by status**: Find only out-of-sync indexes using the `out_of_sync` query parameter

### Index Information

Each search index includes:

| Property      | Description                                             |
|---------------|---------------------------------------------------------|
| `catalog_id`  | The ID of the catalog this index belongs to             |
| `release_id`  | The ID of the catalog release this index was built from |
| `out_of_sync` | Whether the index needs to be rebuilt                   |

### Reindexing

When indexes are out of sync, use the reindex endpoint in [Jobs](/docs/api/pxm/catalog-search/jobs) to rebuild them. Reindexing ensures your search indexes reflect the current indexable field configuration.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Search Profiles

Search Profiles are configuration objects that control how search queries are executed. They provide a powerful way to customize search relevance, filtering, and ranking without requiring code changes, enabling merchandisers and business users to optimize the search experience.

### How Search Profiles Work

A Search Profile defines:

- **Which fields to search**: Select which product fields are included in search queries
- **Field weights**: Assign relative importance to each field for relevance ranking
- **Default filters**: Apply business rules that filter results for all searches
- **Boost rules**: Promote or demote products based on specific conditions
- **Match type**: Control how scores from multiple fields are combined

When a search request is made, the system uses the specified profile (or the default profile) to configure the search behavior.

### Search Profile Components

| Component         | Description                                                                               |
|-------------------|-------------------------------------------------------------------------------------------|
| `slug`            | Unique identifier used to reference the profile in search requests                        |
| `fields`          | List of fields to search with optional weights for relevance ranking                      |
| `filters`         | Default filter expressions applied to all searches using this profile                     |
| `boosts`          | Rules for promoting or demoting products based on conditions                              |
| `text_match_type` | How to combine scores when multiple fields match (`max_score`, `max_weight`, `sum_score`) |

### Field Weights

Field weights control how important each field is when ranking search results. Higher weights mean matches in that field contribute more to the relevance score. Weights must be in the range `[0, 15]`.

**Example**: A profile with `name` (weight 10) and `description` (weight 5) will rank products with search term matches in the name higher than those with matches only in the description.

### Filters

Profile filters enforce business rules that apply to all searches:

- Ensure only live/published products appear in results
- Restrict results to specific categories or channels
- Hide products based on visibility settings

Multiple filters are combined with OR logic, then ANDed with any filters in the search request.

### Boost Rules

Boost rules allow you to promote or demote products in search results:

- **Positive weights**: Push matching products to the top of results
- **Negative weights**: Push matching products to the bottom (burying)
- **Zero weight**: No effect on ranking

Rules are evaluated in weight order, and the first matching rule determines the product's boost.

### Text Match Types

| Type         | Description                                                                            |
|--------------|----------------------------------------------------------------------------------------|
| `max_score`  | Uses the highest score from any single matching field. Prioritizes match quality.      |
| `max_weight` | Uses the score from the highest-weighted matching field. Prioritizes field importance. |
| `sum_score`  | Sums weighted scores from all matching fields. Rewards multi-field matches.            |

### Default Profile

Each store has a default search profile that is used when no profile is specified in the search request. You can set any profile as the default using the set default endpoint.

### Use Cases

- **A/B testing**: Create multiple profiles with different configurations to test search relevance
- **Channel optimization**: Different profiles for web, mobile, and B2B channels
- **Seasonal merchandising**: Profiles that boost seasonal or promotional products
- **Customer segmentation**: Different ranking strategies for different customer tiers

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Search(Catalog-search)

The Search API enables you to search for products in your published catalogs. Search provides powerful capabilities including full-text search, filtering, faceting, and sorting to help shoppers find products quickly and efficiently.

### How Search Works

When you publish a catalog with search enabled, the catalog's products are automatically indexed for search. The search index contains product data optimized for fast querying, including product names, descriptions, SKUs, categories, prices, and any custom fields you've configured.

There are two types of search operations:

- **Search**: Execute a single search query against a catalog. Use the GET endpoint for simple searches with query parameters.
- **Multi-search**: Execute multiple search queries in a single request. Use the POST endpoint to batch searches together for improved performance.

### Search Features

- **Full-text search**: Search across product names, descriptions, SKUs, and custom fields with typo tolerance and relevance ranking
- **Filtering**: Narrow results using conditions on product attributes, categories, prices, and custom fields
- **Faceting**: Get aggregated counts for attribute values to build dynamic navigation and refinement options
- **Sorting**: Order results by price, name, custom fields, or relevance score
- **Highlighting**: Get highlighted snippets showing where search terms match in product fields
- **Autocomplete**: Get search suggestions as shoppers type their queries

### Shopper Context

Search results are personalized based on the shopper's context. The system automatically determines which catalog and prices to use based on:

- **Channel**: The shopping experience (web, mobile, B2B portal)
- **Account**: For B2B scenarios, the account and parent accounts
- **Customer**: The logged-in customer's segment
- **Tags**: Custom context tags for advanced segmentation

This context is provided via request headers and is used to resolve the appropriate catalog rules and price books.

### Admin vs Shopper Endpoints

- **Shopper endpoints** (`/pcm/catalog/search`, `/pcm/catalog/multi-search`): Use shopper context headers to automatically resolve the correct catalog and prices.
- **Admin endpoints** (`/pcm/catalogs/{catalog_id}/releases/{release_id}/search`): Directly specify the catalog and release to search, useful for previewing releases or testing.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Searchable Fields

The Searchable Fields API returns a list of all fields available for searching, filtering, faceting, and sorting in your search queries. This includes both the standard product fields that are indexed by default and any custom fields you've added through Indexable Fields.

### Using Searchable Fields

Use this endpoint to:

- **Discover available fields**: See all fields that can be used in search queries
- **Build dynamic UIs**: Programmatically generate filter and facet options based on available fields
- **Validate configurations**: Verify that your indexable fields have been properly added to the schema

### Field Properties

Each searchable field includes:

| Property | Description |
| --- | --- |
| `name` | The field name to use in search queries |
| `type` | The data type (`string`, `int32`, `int64`, `float`, `bool`) |
| `facetable` | Whether the field can be used for faceting |
| `sortable` | Whether the field can be used for sorting |
| `locale` | The language code for text fields |

### Standard vs Custom Fields

- **Standard fields**: Built-in fields like `name`, `description`, `sku`, `meta.search.nodes.name` that are always available
- **Custom fields**: Fields added through Indexable Fields from your product extensions

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Set search profile as default

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Set search profile as default"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/catalogs/search-profiles/{search_profile_id}/default"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Set a search profile as the default.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"search_profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the search profile","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"ProfileID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully updated the search profile","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the search profile.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_profile`.","type":"string","example":"catalog_search_profile","enum":["catalog_search_profile"],"title":"SearchProfileType"},"attributes":{"type":"object","required":["slug","description","fields","force_use_default_price_for_faceting_and_sorting"],"properties":{"slug":{"type":"string","description":"The unique slug of the search profile. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","example":"default","pattern":"^[a-zA-Z0-9_.-]+$","minLength":1},"description":{"type":"string","description":"The description of the search profile.","example":"Default search profile","default":""},"fields":{"type":"array","description":"A collection of search fields","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the search field.","example":"name","minLength":1},"weight":{"type":"integer","description":"The relative weight to give each field when ranking results. This can be used to boost fields in priority, when looking for matches.\nIf no explicit weights are provided for all fields, fields earlier in the fields list will be considered to have greater weight.\nIf no explicit weights are provided for some fields, the default weight of zero (0) will be used for the fields with no explicit weight.\n","example":10,"minimum":0,"maximum":15},"num_typos":{"type":"integer","description":"Per-field override for the maximum number of typographical errors [Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed\nwhen matching this field. Accepted values: 0 (exact match only), 1, or 2.\nOverrides `typo_tolerance.num_typos` for this field. Falls back to `typo_tolerance.num_typos`\nif set, otherwise default of 2.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`typo_tolerance.min_len_to_allow_single_character_correction` (default 4) and\n`typo_tolerance.min_len_to_allow_two_character_correction` (default 7):\n- A token shorter than the single-character threshold gets **no** typo correction, even with `num_typos` 1 or 2.\n- A token at least as long as the single-character threshold but shorter than the two-character threshold is corrected by **at most one** character, even with `num_typos` of 2.\n- Only tokens at least as long as the two-character threshold can use the full two corrections.\n\nFor example, with the defaults, \"appla\" → \"apple\" (length 5, one correction) is allowed,\nbut a 5-character query with two mistakes is not corrected even with `num_typos` of 2, because two-character correction requires a token of at least 7 characters.\n","minimum":0,"maximum":2,"example":1},"prefix":{"type":"boolean","description":"Per-field override for prefix (partial match) behavior on the last query token.\nWhen true, the last word is treated as a prefix; when false, it must match exactly.\nFor example, when true, a search request for \"red app\" matches \"red apple\".\nOverrides the profile-level `prefix` for this field. Falls back to the profile-level\n`prefix` if set, otherwise default of true.\n\nThe primary use case is to show results as the user is typing in the search box.\n","example":true}},"title":"SearchField"}},"text_match_type":{"type":"string","description":"When a search profile has multiple fields defined, this parameter determines how the representative text match score of a product is calculated.\n\n- `max_score (Default)`: In this mode, the products's representative score is simply the highest score from any single matching field. The field weights are used only as a tie-breaker if two products have the exact same highest score. This mode prioritizes the quality of the match in the single best-matching field.\n- `max_weight`: This mode uses the score from the matching field that has the highest weight. This means a partial, lower-quality match on a heavily weighted field (e.g., name) can be prioritized over a perfect match on a lower-weighted field (e.g., description). This mode prioritizes matches in the most important fields, regardless of match quality.\n- `sum_score`: This mode calculates a holistic score by summing the weighted scores from all matching fields. Its advantage is that it rewards products that match a query across multiple attributes. However, it carries the risk that a product with many weak, partial matches across several low-weighted fields could outrank a product with a single strong, perfect match in a high-weighted field.\n","enum":["max_score","max_weight","sum_score"],"example":"max_score","title":"TextMatchType"},"filters":{"type":"array","description":"Optional list of filter expressions to apply to search results. Multiple filters in the array are combined using OR logic (records matching filter1 || filter2 || ... filterN).\nTo combine conditions with AND logic, include multiple conditions within a single filter string (e.g., \"meta.search.categories.lvl1:=`All Products > Mens Shoes` && meta.display_price.without_tax.float_price:>100\").\nThese profile-level filters are ANDed with any filters provided in the search request via the filter_by parameter, resulting in: (profile_filter1 || profile_filter2 || ... profile_filterN) && request_filters.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"exclusions":{"type":"array","description":"A collection of exclusion expressions to apply to search results. Multiple exclusions in the array are combined using OR logic (records matching exclusion1 || exclusion2 || ... exclusionN).","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"boosts":{"type":"array","items":{"type":"object","description":"Defines a boosting rule that assigns a score to products matching a specific field value.","required":["condition","weight"],"properties":{"condition":{"type":"string","description":"A filter expression used to identify a subset of products for boosting. This follows the standard filter_by syntax.\n\nIt can be a simple condition like `meta.search.nodes.name:=\\`Electronics\\`` or complex like `meta.search.nodes.name:=\\`Electronics\\` && extensions.products(Details).brand:=Nike`.\n","minLength":1,"example":"meta.search.nodes.name:=\\`Electronics\\`"},"weight":{"type":"integer","description":"A numerical value representing the boost intensity. Products matching the criteria are assigned this value. Higher weights will cause products to appear earlier in the results.\n\n**Impact of Weights:**\n* **Boost (Positive):** Pushes products to the top.\n* **No affect (Zero):** Has no affect. Treated the same as products that match no rules.\n* **Bury (Negative):** Pushes products to the bottom.\n\n**Rule Evaluation:** The system uses \"Short-circuit\" evaluation. The engine stops at the **first matching rule**.\nThis means the weight of the first matching rule will be used as the product weight to sort the results.\nIf no rules match, the product is assigned a weight of `0`.\n","example":5}},"title":"SearchBoostRule"},"x-go-type-skip-optional-pointer":true},"prefix":{"type":"boolean","description":"Profile-level default for prefix (partial match) behavior on the last query token. When true, the last word in the query is treated as a prefix for all fields that do not have an explicit per-field prefix value. For example, a search request for \"red app\" matches \"red apple\". When false, the last word must match exactly. If omitted, default of true applies. Per-field prefix values override this setting.\nThe primary use case is to show results as the user is typing in the search box.\n","example":true},"typo_tolerance":{"type":"object","nullable":true,"description":"Optional typo tolerance configuration applied at search time.\nAll fields are optional; defaults are noted on each field.\n","properties":{"num_typos":{"type":"integer","description":"Profile-level default for the maximum number of typographical errors\n[Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed when matching any field.\nAccepted values: 0 (exact match only), 1, or 2.\nPer-field `num_typos` values override this setting. If omitted, default of 2 applies.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`min_len_to_allow_single_character_correction` (default 4) and\n`min_len_to_allow_two_character_correction` (default 7): a token shorter than the\nsingle-character threshold gets no correction at all, and a token shorter than the\ntwo-character threshold is corrected by at most one character — even when `num_typos` is 2.\nSee those two fields for details.\n","minimum":0,"maximum":2,"example":1},"min_len_to_allow_single_character_correction":{"type":"integer","description":"Minimum query-token length required before a single-character typo correction is attempted. This works together with `num_typos`: a token shorter than this length receives no typo correction at all, regardless of `num_typos`. For example, when set to 4, a search for \"appla\" will match \"apple\", but a search for \"apa\" will not match \"app\" because the length of \"apa\" is 3.\nDefault: 4.\n","minimum":1,"example":3},"min_len_to_allow_two_character_correction":{"type":"integer","description":"Minimum query-token length required before a two-character typo correction is attempted. This works together with `num_typos`: even when `num_typos` is 2, a token shorter than this length is corrected by at most one character (and a token shorter than `min_len_to_allow_single_character_correction` is not corrected at all). For example, with the default of 7, the 7-character query \"monetar\" can be corrected to \"monitor\" (two corrections), but a 6-character query with two mistakes cannot.\nDefault: 7\n","minimum":1,"example":7},"typo_tokens_threshold":{"type":"integer","description":"Typo-corrected query variations are only generated if the number of exact results\nfound is fewer than this value. Set to 0 to disable typo tolerance entirely.\nFor example, when set to 5 and the search result only has 3 results, the search engine will apply typo correction to try to return 5 or more results.\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_threshold":{"type":"integer","description":"For multi-word queries, tokens are progressively dropped if the number of results\nis fewer than this value. Set to 0 to disable token dropping.\n\nFor example, when set to 5 and the search result only has 3 results for \"red apple\" search,\nthe search engine will drop the last token \"apple\" and find more results with just by searching for \"red\".\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_mode":{"type":"string","description":"Controls the direction in which tokens are dropped from a multi-word query when\nresults fall below drop_tokens_threshold.\n- `right_to_left` (default): drops tokens from the right end of the query first.\n- `left_to_right`: drops tokens from the left end first.\n- `both_sides:N`: drops from both ends, limited to queries of N tokens or fewer\n  (e.g. `both_sides:3` applies only to queries with 3 or fewer tokens).\n","example":"right_to_left"},"enable_typos_for_numerical_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that are purely numeric (every character is a digit, e.g. \"98765\"). Such a token must then match exactly.\nDefault: true\n","example":true},"enable_typos_for_special_char_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that contain at least one non-alphanumeric character\n(any character outside `a-z`, `A-Z`, `0-9`), forcing such tokens to match exactly.\nUseful for keeping product codes / SKUs precise.\n\nTokens like `abc-123`, `abc-def`, `123-456`, and `v1.2.0` are affected;\na plain alphanumeric token like `abc123` is not.\n\nNote: the special character must be indexed on the field (via `symbols_to_index`);\notherwise the search engine removes the special characters from tokens\n(e.g. a token like v1.2.0 becomes v120) and it no longer qualifies.\n\nDefault: true\n","example":true},"split_join_tokens":{"type":"string","description":"Controls whether compound words and multi-word phrases are treated as equivalent during search.\nFor example, a query for \"nonstick\" may also match \"non stick\", and vice versa.\n- `fallback` (default): tries the original query form first; falls back to split/joined variants if results are insufficient.\n- `always`: always generates both split and joined token variants alongside the original query.\n- `off`: disables split/join token handling.\n","enum":["fallback","always","off"],"example":"fallback"}},"title":"TypoTolerance"},"synonym_settings":{"type":"object","nullable":true,"description":"Optional synonym tuning applied at search time. These settings control how synonym\nmatches are ranked and how query tokens are resolved against the synonym sets attached\nto the search profile. All fields are optional; defaults are noted on each field.\nThey only have an observable effect when synonym sets are attached to the resolved profile.\n","properties":{"demote_synonym_match":{"type":"boolean","description":"When true, results matched via a synonym are ranked below direct (non-synonym) matches. When false, synonym matches and direct matches are ranked equally.\nDefault: false\n","example":true},"synonym_resolution_allowed_on_prefix":{"type":"boolean","description":"When true, an incomplete (prefix) query token can resolve to a synonym, i.e. synonym\nexpansion is attempted on prefix tokens.\n\n**This is not the same as the `prefix` setting.** The `prefix` setting treats only the\n**last** word of the query as a prefix; `synonym_resolution_allowed_on_prefix` applies\nprefix matching at **every** token position when looking words up in the synonym sets —\nthere is no last-token special-casing.\n\n**Exact matches always win.** A query token that exactly equals a synonym key resolves\nregardless of this flag; the prefix behavior only affects the fuzzy fallback for tokens\nwith no exact synonym-key match. It composes with\n`number_of_typos_allowed_when_resolving_synonyms`, which governs typo tolerance during\nthe prefix/fuzzy lookup.\n\nWorked example (synonym keys `red`, `apple`, `apparel`):\n- `red app`: `red` matches exactly; `app` prefix-matches both `apple` and `apparel` — both expand.\n- `re app`: `re` prefix-matches `red` **and** `app` prefix-matches `apple`/`apparel` — both expand.\n  The regular `prefix` setting would only treat the last word (`app`) as a prefix; here every\n  position is prefix-matched.\n\nDefault: false\n","example":true},"number_of_typos_allowed_when_resolving_synonyms":{"type":"integer","description":"Number of typos allowed when resolving synonyms. Enables fuzzy synonym matching\nso that a misspelled query term can still trigger a synonym expansion for the\nsynonym sets attached to the search profile.\nAccepted values: 0 (exact synonym match only, default), 1, or 2.\n","minimum":0,"maximum":2,"example":0}},"title":"SynonymSettings"},"synonym_sets":{"type":"array","description":"Optional list of synonym set IDs to apply at search time. Each synonym set must exist and must have been synced to the search engine at least once. Organization-level search profiles may only reference organization-level synonym sets. Store-level search profiles may reference organization-level and same-store synonym sets.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"force_use_default_price_for_faceting_and_sorting":{"type":"boolean","description":"When set to true, the default price is used for faceting and sorting for segmented catalogs even if the catalog rule has a supported price book.","default":false,"example":true}},"title":"SearchProfileAttributes"},"meta":{"type":"object","required":["default","owner"],"properties":{"default":{"type":"boolean","description":"Whether this is the default search profile.","example":true},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"SearchProfileMeta"}},"title":"SearchProfile"}},"title":"SearchProfileResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"403":{"description":"Permission denied - search profile owned by the organization","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"404":{"description":"Search profile not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Stopword Sets

Stopword Sets allow you to define sets of common words (such as "the", "a", "an", "is") that should be ignored during search queries. By removing these low-value terms from search processing, you can improve search relevance and reduce noise in results.

### How Stopword Sets Work

A stopword set is a named container of stopword words. Each set belongs to an organization or store and is synced asynchronously. Once synced, the stopwords are applied during search query processing to filter out the specified terms.

### Common Stopwords

Stopword sets contain a flat list of words to ignore:

- **Common articles**: "the", "a", "an"
- **Prepositions**: "in", "on", "at", "for"
- **Conjunctions**: "and", "or", "but"

### Sync Status

Stopword sets are synced asynchronously. The sync status is tracked and exposed in API responses:

| Status           | Description                                                    |
|------------------|----------------------------------------------------------------|
| `pending_sync`   | Set has been created or updated in MongoDB but not yet synced  |
| `synced`         | Set has been successfully synced                               |
| `sync_failed`    | The last sync attempt failed                                   |
| `pending_delete` | Set is marked for deletion; a background worker will remove it |

### Tenancy

Stopword sets follow the same tenancy model as other resources:

- **Organization-scoped sets**: Managed by the organization; apply across all stores
- **Store-scoped sets**: Managed by the store; apply only to that store

Stores cannot modify organization-scoped stopword sets.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Synonym Sets

Synonym Sets allow you to define groups of equivalent or related terms so that searches for one term also return results for its synonyms. This helps shoppers find products regardless of the specific terminology they use.

### How Synonym Sets Work

A synonym set is a named container of synonym items. Each set belongs to an organization or store and is synced asynchronously. Once synced, a set can be attached to one or more search profiles; its synonym rules are then applied during searches that use those profiles to expand queries with matching terms.

### Synonym Types

Each item within a synonym set can be either multi-way or one-way:

- **Multi-way synonyms**: All terms are treated as equivalent. Searching for any term in the list returns results for all of them. For example, `["sneakers", "trainers", "running shoes"]` means a search for "trainers" also returns results for "sneakers" and "running shoes".
- **One-way synonyms**: Searches for a `root` term also match the `synonyms`, but not vice versa. For example, with `root: "jacket"` and `synonyms: ["blazer", "coat"]`, searching for "jacket" also returns results for "blazer" and "coat", but searching for "blazer" does not return results for "jacket".

### Synonym Item Configuration

Each item within a synonym set supports the following options:

| Option             | Required | Description                                                                                                  |
|--------------------|----------|--------------------------------------------------------------------------------------------------------------|
| `id`               | Yes      | Unique identifier for the item within the set. Alphanumeric characters, hyphens, and underscores only.       |
| `synonyms`         | Yes      | List of synonym terms. Minimum 1 if `root` is provided (one-way), minimum 2 if `root` is absent (multi-way). |
| `root`             | No       | Makes this a one-way synonym. Must not also appear in the `synonyms` array.                                  |
| `locale`           | No       | ISO 639 language code for this synonym item.                                                                 |
| `symbols_to_index` | No       | Special characters to preserve as part of tokens. Each element must be exactly one character.                |

### Sync Status

Synonym sets are synced asynchronously. The sync status is tracked and exposed in API responses:

| Status           | Description                                                    |
|------------------|----------------------------------------------------------------|
| `pending_sync`   | Set has been created or updated in MongoDB but not yet synced  |
| `synced`         | Set has been successfully synced                               |
| `sync_failed`    | The last sync attempt failed                                   |
| `pending_delete` | Set is marked for deletion; a background worker will remove it |

### Tenancy

Synonym sets follow the same tenancy model as other resources:

- **Organization-scoped sets**: Managed by the organization; apply across all stores
- **Store-scoped sets**: Managed by the store; apply only to that store

Stores cannot modify organization-scoped synonym sets.

### Using Synonym Sets in Search Profiles

Synonym sets only take effect once they are attached to a [search profile](/docs/api/pxm/catalog-search/search-profiles) via its `synonym_sets` attribute. At search time, the synonym sets of the resolved search profile are applied to the query.

When attaching a synonym set to a search profile:

- The set must exist and be accessible by the calling tenant. Organization-level search profiles may only reference organization-level sets; store-level search profiles may reference organization-level and same-store sets.
- The set must have been synced at least once. A set in `pending_sync` or `sync_failed` state can still be used if it was previously synced — its last synced state continues to apply.

A synonym set cannot be deleted while it is referenced by any search profile; the delete request is rejected with a `409 Conflict` until the reference is removed.

### Use Cases

- **Regional terminology**: Map British and American English terms (e.g., "trousers" ↔ "pants")
- **Brand equivalents**: Link product category names with common alternatives
- **Industry jargon**: Ensure technical terms match colloquial ones
- **Abbreviations**: Map abbreviations to their full forms (e.g., "tee" → "t-shirt")

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Update indexable fields

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update indexable fields"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/catalogs/indexable-fields/{indexable_fields_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update additional fields to be indexed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"indexable_fields_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the indexable fields","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"IndexableFieldsID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"description":"The unique identifier of the indexable fields. Must match the ID specified in the request path.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_indexable_fields`.","type":"string","example":"catalog_search_indexable_fields","enum":["catalog_search_indexable_fields"],"title":"IndexableFieldsType"},"attributes":{"type":"object","properties":{"fields":{"type":"array","description":"A collection of indexable fields","title":"IndexableFields","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the field to index. Two formats are supported:\n\n- **Extension fields**: `extensions.products(<template_slug>).<field_name>` — indexes a field from a product extension template. The field must exist and be enabled in the flows service.\n- **Shopper attribute fields**: `shopper_attributes.<attribute_name>` — indexes a merchant-defined shopper attribute. Always typed as `string`. The attribute name must be no longer than **64 characters** and can only contain alphanumeric characters, underscores (`_`), and hyphens (`-`).\n- **Admin attribute fields**: `admin_attributes.<attribute_name>` — indexes a merchant-defined admin attribute. Always typed as `string`. The attribute name must be no longer than **64 characters** and can only contain alphanumeric characters, underscores (`_`), and hyphens (`-`).\n","example":"extensions.products(clothing).color","minLength":1},"facetable":{"type":"boolean","description":"Enables faceting on the field.","default":false,"example":true},"sortable":{"type":"boolean","description":"When set to true, the field will be sortable. Default: true for numbers, false otherwise.","example":true},"locale":{"type":"string","description":"For configuring language specific tokenization, e.g. jp for Japanese. Default: en which also broadly supports most European languages. For valid values, see [ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).","default":"en","example":"en"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting. Each element must be a single character.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide per-field special characters to index for this field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting. Each element must be a single character.\n"}},"title":"IndexableFieldRequest"},"example":[{"name":"extensions.products(clothing).color","facetable":false,"sortable":false,"locale":"en"},{"name":"shopper_attributes.fabric","facetable":false,"sortable":false},{"name":"admin_attributes.internal_grade","sortable":true}]},"core_field_overrides":{"type":"array","description":"Per-field configuration for core product fields (e.g. name, description).","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the core field to configure. Must be one of the supported core fields.\n","example":"name"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this core field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting. Each element must be a single character.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide per-field special characters to index for this core field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting. Each element must be a single character.\n"},"sortable":{"type":"boolean","description":"When set to true, enables sorting on this core field. Only supported for specific core fields.\n","example":true},"facetable":{"type":"boolean","description":"When set to true, enables faceting on this core field. A re-index is required for the change to take effect.\n","example":true}},"title":"CoreFieldOverride"}},"token_separators":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters to use as token separators across all the index fields, in addition to spaces and newlines. Each element must be a single character. Defaults to none set.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide list of special characters that should be indexed as part of the tokens across the all index fields. Each element must be a single character. Defaults to none set.\n"}},"title":"IndexableFieldsRequestAttributes"}},"title":"IndexableFieldsUpdateRequestData"}},"title":"IndexableFieldsUpdateRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully updated indexable fields","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier of the indexable fields.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_indexable_fields`.","type":"string","example":"catalog_search_indexable_fields","enum":["catalog_search_indexable_fields"],"title":"IndexableFieldsType"},"attributes":{"type":"object","properties":{"fields":{"type":"array","x-go-type-skip-optional-pointer":true,"description":"A collection of indexable fields","title":"IndexableFields","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","description":"The name of the field.","example":"extensions.products(clothing).color","minLength":1},"type":{"type":"string","description":"The type of the field.","enum":["string","int32","int64","bool","float"],"example":"string","x-go-type":"model.FieldType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"},"title":"FieldType"},"facetable":{"type":"boolean","description":"Enables faceting on the field.","default":false,"example":true},"sortable":{"type":"boolean","description":"When set to true, the field will be sortable. Default: true for numbers, false otherwise.","example":true},"locale":{"type":"string","description":"For configuring language specific tokenization, e.g. jp for Japanese. Default: en which also broadly supports most European languages. For valid values, see [ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes).","default":"en","example":"en"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Provide per-field special characters to index for this field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting.\n"}},"title":"IndexableField"},"example":[{"name":"extensions.products(clothing).color","type":"string","facetable":false,"sortable":false,"locale":"en"},{"name":"shopper_attributes.fabric","type":"string","facetable":false,"sortable":false},{"name":"admin_attributes.internal_grade","type":"string","sortable":true}]},"core_field_overrides":{"type":"array","x-go-type-skip-optional-pointer":true,"description":"Per-field configuration for core product fields (e.g. name, description).","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the core field to configure. Must be one of the supported core fields.\n","example":"name"},"stem":{"type":"boolean","description":"When true, enables word stemming on this field using [Snowball stemmer](https://snowballstem.org/). Stemming reduces words to their root form at index and query time, so a search for \"running\" will also match products containing \"run\", \"runs\", or \"runner\". This improves search recall for descriptive text fields where shoppers may use different word forms than those used in product data. Only valid for string-typed fields. Defaults to false.\n","example":true,"title":"Stem"},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Per-field token separators for this core field. Overrides the collection-level token_separators for this field. An empty array defers to the collection-level setting. Each element must be a single character.\nFor example, take text `non-tech`. By default, it will be tokenized to `nontech`. So, search for `non tech` will not match the product. Set `token_separators: [\"-\"]`. Then it will be tokenized to `non` and `tech`. Now, search for both `non-tech` and `non tech` will match this product.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"By default, special characters are removed from fields when indexing and searching for them. Provide per-field special characters to index for this core field. Overrides the collection-level symbols_to_index for this field. An empty array defers to the collection-level setting. Each element must be a single character.\n"},"sortable":{"type":"boolean","description":"When set to true, enables sorting on this core field. Only supported for specific core fields.\n","example":true},"facetable":{"type":"boolean","description":"When set to true, enables faceting on this core field. A re-index is required for the change to take effect.\n","example":true}},"title":"CoreFieldOverride"}},"token_separators":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters used as token separators across the entire collection.\n"},"symbols_to_index":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"string","minLength":1,"maxLength":1},"description":"Characters indexed as part of tokens across the entire collection.\n"}},"title":"IndexableFieldsAttributes"},"meta":{"type":"object","required":["owner"],"properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"IndexableFieldsMeta"}},"title":"IndexableFields"}},"title":"IndexableFieldsResponse"}}}},"400":{"description":"Bad request - invalid search parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"403":{"description":"Permission denied - indexable fields owned by the organization","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"404":{"description":"Indexable fields not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"409":{"description":"Conflict - reindexing job queued or in progress","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update search profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update search profile"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/catalogs/search-profiles/{search_profile_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a search profile.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"search_profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the search profile","example":"ac107ce9-96ac-4bd5-aa3d-59f40b91279b","x-go-name":"ProfileID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"description":"The unique identifier of the search profile. Must match the ID specified in the request path.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_profile`.","type":"string","example":"catalog_search_profile","enum":["catalog_search_profile"],"title":"SearchProfileType"},"attributes":{"type":"object","properties":{"slug":{"type":"string","description":"The unique slug of the search profile. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","example":"default","pattern":"^[a-zA-Z0-9_.-]+$","minLength":1},"description":{"type":"string","description":"The description of the search profile.","example":"Default search profile"},"fields":{"type":"array","description":"A collection of search fields","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the search field.","example":"name","minLength":1},"weight":{"type":"integer","description":"The relative weight to give each field when ranking results. This can be used to boost fields in priority, when looking for matches.\nIf no explicit weights are provided for all fields, fields earlier in the fields list will be considered to have greater weight.\nIf no explicit weights are provided for some fields, the default weight of zero (0) will be used for the fields with no explicit weight.\n","example":10,"minimum":0,"maximum":15},"num_typos":{"type":"integer","description":"Per-field override for the maximum number of typographical errors [Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed\nwhen matching this field. Accepted values: 0 (exact match only), 1, or 2.\nOverrides `typo_tolerance.num_typos` for this field. Falls back to `typo_tolerance.num_typos`\nif set, otherwise default of 2.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`typo_tolerance.min_len_to_allow_single_character_correction` (default 4) and\n`typo_tolerance.min_len_to_allow_two_character_correction` (default 7):\n- A token shorter than the single-character threshold gets **no** typo correction, even with `num_typos` 1 or 2.\n- A token at least as long as the single-character threshold but shorter than the two-character threshold is corrected by **at most one** character, even with `num_typos` of 2.\n- Only tokens at least as long as the two-character threshold can use the full two corrections.\n\nFor example, with the defaults, \"appla\" → \"apple\" (length 5, one correction) is allowed,\nbut a 5-character query with two mistakes is not corrected even with `num_typos` of 2, because two-character correction requires a token of at least 7 characters.\n","minimum":0,"maximum":2,"example":1},"prefix":{"type":"boolean","description":"Per-field override for prefix (partial match) behavior on the last query token.\nWhen true, the last word is treated as a prefix; when false, it must match exactly.\nFor example, when true, a search request for \"red app\" matches \"red apple\".\nOverrides the profile-level `prefix` for this field. Falls back to the profile-level\n`prefix` if set, otherwise default of true.\n\nThe primary use case is to show results as the user is typing in the search box.\n","example":true}},"title":"SearchField"}},"text_match_type":{"type":"string","description":"When a search profile has multiple fields defined, this parameter determines how the representative text match score of a product is calculated.\n\n- `max_score (Default)`: In this mode, the products's representative score is simply the highest score from any single matching field. The field weights are used only as a tie-breaker if two products have the exact same highest score. This mode prioritizes the quality of the match in the single best-matching field.\n- `max_weight`: This mode uses the score from the matching field that has the highest weight. This means a partial, lower-quality match on a heavily weighted field (e.g., name) can be prioritized over a perfect match on a lower-weighted field (e.g., description). This mode prioritizes matches in the most important fields, regardless of match quality.\n- `sum_score`: This mode calculates a holistic score by summing the weighted scores from all matching fields. Its advantage is that it rewards products that match a query across multiple attributes. However, it carries the risk that a product with many weak, partial matches across several low-weighted fields could outrank a product with a single strong, perfect match in a high-weighted field.\n","enum":["max_score","max_weight","sum_score"],"example":"max_score","title":"TextMatchType"},"filters":{"type":"array","description":"Optional list of filter expressions to apply to search results. Multiple filters in the array are combined using OR logic (records matching filter1 || filter2 || ... filterN).\nTo combine conditions with AND logic, include multiple conditions within a single filter string (e.g., \"meta.search.categories.lvl1:=`All Products > Mens Shoes` && meta.display_price.without_tax.float_price:>100\").\nThese profile-level filters are ANDed with any filters provided in the search request via the filter_by parameter, resulting in: (profile_filter1 || profile_filter2 || ... profile_filterN) && request_filters.\n","items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"exclusions":{"type":"array","description":"A collection of exclusion expressions to apply to search results. Multiple exclusions in the array are combined using OR logic (records matching exclusion1 || exclusion2 || ... exclusionN).","items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"boosts":{"type":"array","items":{"type":"object","description":"Defines a boosting rule that assigns a score to products matching a specific field value.","required":["condition","weight"],"properties":{"condition":{"type":"string","description":"A filter expression used to identify a subset of products for boosting. This follows the standard filter_by syntax.\n\nIt can be a simple condition like `meta.search.nodes.name:=\\`Electronics\\`` or complex like `meta.search.nodes.name:=\\`Electronics\\` && extensions.products(Details).brand:=Nike`.\n","minLength":1,"example":"meta.search.nodes.name:=\\`Electronics\\`"},"weight":{"type":"integer","description":"A numerical value representing the boost intensity. Products matching the criteria are assigned this value. Higher weights will cause products to appear earlier in the results.\n\n**Impact of Weights:**\n* **Boost (Positive):** Pushes products to the top.\n* **No affect (Zero):** Has no affect. Treated the same as products that match no rules.\n* **Bury (Negative):** Pushes products to the bottom.\n\n**Rule Evaluation:** The system uses \"Short-circuit\" evaluation. The engine stops at the **first matching rule**.\nThis means the weight of the first matching rule will be used as the product weight to sort the results.\nIf no rules match, the product is assigned a weight of `0`.\n","example":5}},"title":"SearchBoostRule"}},"prefix":{"type":"boolean","nullable":true,"description":"Profile-level default for prefix (partial match) behavior on the last query token. When true, the last word in the query is treated as a prefix for all fields that do not have an explicit per-field prefix value. For example, a search request for \"red app\" matches \"red apple\". When false, the last word must match exactly. If omitted, default of true applies. Per-field prefix values override this setting.\nThe primary use case is to show results as the user is typing in the search box.\n","example":true},"typo_tolerance":{"type":"object","nullable":true,"description":"Optional typo tolerance configuration applied at search time.\nAll fields are optional; defaults are noted on each field.\n","properties":{"num_typos":{"type":"integer","description":"Profile-level default for the maximum number of typographical errors\n[Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed when matching any field.\nAccepted values: 0 (exact match only), 1, or 2.\nPer-field `num_typos` values override this setting. If omitted, default of 2 applies.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`min_len_to_allow_single_character_correction` (default 4) and\n`min_len_to_allow_two_character_correction` (default 7): a token shorter than the\nsingle-character threshold gets no correction at all, and a token shorter than the\ntwo-character threshold is corrected by at most one character — even when `num_typos` is 2.\nSee those two fields for details.\n","minimum":0,"maximum":2,"example":1},"min_len_to_allow_single_character_correction":{"type":"integer","description":"Minimum query-token length required before a single-character typo correction is attempted. This works together with `num_typos`: a token shorter than this length receives no typo correction at all, regardless of `num_typos`. For example, when set to 4, a search for \"appla\" will match \"apple\", but a search for \"apa\" will not match \"app\" because the length of \"apa\" is 3.\nDefault: 4.\n","minimum":1,"example":3},"min_len_to_allow_two_character_correction":{"type":"integer","description":"Minimum query-token length required before a two-character typo correction is attempted. This works together with `num_typos`: even when `num_typos` is 2, a token shorter than this length is corrected by at most one character (and a token shorter than `min_len_to_allow_single_character_correction` is not corrected at all). For example, with the default of 7, the 7-character query \"monetar\" can be corrected to \"monitor\" (two corrections), but a 6-character query with two mistakes cannot.\nDefault: 7\n","minimum":1,"example":7},"typo_tokens_threshold":{"type":"integer","description":"Typo-corrected query variations are only generated if the number of exact results\nfound is fewer than this value. Set to 0 to disable typo tolerance entirely.\nFor example, when set to 5 and the search result only has 3 results, the search engine will apply typo correction to try to return 5 or more results.\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_threshold":{"type":"integer","description":"For multi-word queries, tokens are progressively dropped if the number of results\nis fewer than this value. Set to 0 to disable token dropping.\n\nFor example, when set to 5 and the search result only has 3 results for \"red apple\" search,\nthe search engine will drop the last token \"apple\" and find more results with just by searching for \"red\".\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_mode":{"type":"string","description":"Controls the direction in which tokens are dropped from a multi-word query when\nresults fall below drop_tokens_threshold.\n- `right_to_left` (default): drops tokens from the right end of the query first.\n- `left_to_right`: drops tokens from the left end first.\n- `both_sides:N`: drops from both ends, limited to queries of N tokens or fewer\n  (e.g. `both_sides:3` applies only to queries with 3 or fewer tokens).\n","example":"right_to_left"},"enable_typos_for_numerical_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that are purely numeric (every character is a digit, e.g. \"98765\"). Such a token must then match exactly.\nDefault: true\n","example":true},"enable_typos_for_special_char_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that contain at least one non-alphanumeric character\n(any character outside `a-z`, `A-Z`, `0-9`), forcing such tokens to match exactly.\nUseful for keeping product codes / SKUs precise.\n\nTokens like `abc-123`, `abc-def`, `123-456`, and `v1.2.0` are affected;\na plain alphanumeric token like `abc123` is not.\n\nNote: the special character must be indexed on the field (via `symbols_to_index`);\notherwise the search engine removes the special characters from tokens\n(e.g. a token like v1.2.0 becomes v120) and it no longer qualifies.\n\nDefault: true\n","example":true},"split_join_tokens":{"type":"string","description":"Controls whether compound words and multi-word phrases are treated as equivalent during search.\nFor example, a query for \"nonstick\" may also match \"non stick\", and vice versa.\n- `fallback` (default): tries the original query form first; falls back to split/joined variants if results are insufficient.\n- `always`: always generates both split and joined token variants alongside the original query.\n- `off`: disables split/join token handling.\n","enum":["fallback","always","off"],"example":"fallback"}},"title":"TypoTolerance"},"synonym_settings":{"type":"object","nullable":true,"description":"Optional synonym tuning applied at search time. These settings control how synonym\nmatches are ranked and how query tokens are resolved against the synonym sets attached\nto the search profile. All fields are optional; defaults are noted on each field.\nThey only have an observable effect when synonym sets are attached to the resolved profile.\n","properties":{"demote_synonym_match":{"type":"boolean","description":"When true, results matched via a synonym are ranked below direct (non-synonym) matches. When false, synonym matches and direct matches are ranked equally.\nDefault: false\n","example":true},"synonym_resolution_allowed_on_prefix":{"type":"boolean","description":"When true, an incomplete (prefix) query token can resolve to a synonym, i.e. synonym\nexpansion is attempted on prefix tokens.\n\n**This is not the same as the `prefix` setting.** The `prefix` setting treats only the\n**last** word of the query as a prefix; `synonym_resolution_allowed_on_prefix` applies\nprefix matching at **every** token position when looking words up in the synonym sets —\nthere is no last-token special-casing.\n\n**Exact matches always win.** A query token that exactly equals a synonym key resolves\nregardless of this flag; the prefix behavior only affects the fuzzy fallback for tokens\nwith no exact synonym-key match. It composes with\n`number_of_typos_allowed_when_resolving_synonyms`, which governs typo tolerance during\nthe prefix/fuzzy lookup.\n\nWorked example (synonym keys `red`, `apple`, `apparel`):\n- `red app`: `red` matches exactly; `app` prefix-matches both `apple` and `apparel` — both expand.\n- `re app`: `re` prefix-matches `red` **and** `app` prefix-matches `apple`/`apparel` — both expand.\n  The regular `prefix` setting would only treat the last word (`app`) as a prefix; here every\n  position is prefix-matched.\n\nDefault: false\n","example":true},"number_of_typos_allowed_when_resolving_synonyms":{"type":"integer","description":"Number of typos allowed when resolving synonyms. Enables fuzzy synonym matching\nso that a misspelled query term can still trigger a synonym expansion for the\nsynonym sets attached to the search profile.\nAccepted values: 0 (exact synonym match only, default), 1, or 2.\n","minimum":0,"maximum":2,"example":0}},"title":"SynonymSettings"},"synonym_sets":{"type":"array","description":"Optional list of synonym set IDs to apply at search time. Each synonym set must exist and must have been synced to the search engine at least once. Organization-level search profiles may only reference organization-level synonym sets. Store-level search profiles may reference organization-level and same-store synonym sets. Set to an empty array to remove all synonym sets from the search profile.\n","items":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"force_use_default_price_for_faceting_and_sorting":{"type":"boolean","description":"When set to true, the default price is used for faceting and sorting for segmented catalogs even if the catalog rule has a supported price book.","example":true}},"title":"SearchProfileUpdateAttributes"}},"title":"SearchProfileUpdateRequestData"}},"title":"SearchProfileUpdateRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully updated search profile","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the search profile.","type":"string","format":"uuid","example":"805103ff-0a37-4f83-8fe0-95a16039bd98","x-go-name":"ID"},"type":{"description":"Represents the type of object being returned. Always `catalog_search_profile`.","type":"string","example":"catalog_search_profile","enum":["catalog_search_profile"],"title":"SearchProfileType"},"attributes":{"type":"object","required":["slug","description","fields","force_use_default_price_for_faceting_and_sorting"],"properties":{"slug":{"type":"string","description":"The unique slug of the search profile. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","example":"default","pattern":"^[a-zA-Z0-9_.-]+$","minLength":1},"description":{"type":"string","description":"The description of the search profile.","example":"Default search profile","default":""},"fields":{"type":"array","description":"A collection of search fields","minItems":1,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"The name of the search field.","example":"name","minLength":1},"weight":{"type":"integer","description":"The relative weight to give each field when ranking results. This can be used to boost fields in priority, when looking for matches.\nIf no explicit weights are provided for all fields, fields earlier in the fields list will be considered to have greater weight.\nIf no explicit weights are provided for some fields, the default weight of zero (0) will be used for the fields with no explicit weight.\n","example":10,"minimum":0,"maximum":15},"num_typos":{"type":"integer","description":"Per-field override for the maximum number of typographical errors [Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed\nwhen matching this field. Accepted values: 0 (exact match only), 1, or 2.\nOverrides `typo_tolerance.num_typos` for this field. Falls back to `typo_tolerance.num_typos`\nif set, otherwise default of 2.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`typo_tolerance.min_len_to_allow_single_character_correction` (default 4) and\n`typo_tolerance.min_len_to_allow_two_character_correction` (default 7):\n- A token shorter than the single-character threshold gets **no** typo correction, even with `num_typos` 1 or 2.\n- A token at least as long as the single-character threshold but shorter than the two-character threshold is corrected by **at most one** character, even with `num_typos` of 2.\n- Only tokens at least as long as the two-character threshold can use the full two corrections.\n\nFor example, with the defaults, \"appla\" → \"apple\" (length 5, one correction) is allowed,\nbut a 5-character query with two mistakes is not corrected even with `num_typos` of 2, because two-character correction requires a token of at least 7 characters.\n","minimum":0,"maximum":2,"example":1},"prefix":{"type":"boolean","description":"Per-field override for prefix (partial match) behavior on the last query token.\nWhen true, the last word is treated as a prefix; when false, it must match exactly.\nFor example, when true, a search request for \"red app\" matches \"red apple\".\nOverrides the profile-level `prefix` for this field. Falls back to the profile-level\n`prefix` if set, otherwise default of true.\n\nThe primary use case is to show results as the user is typing in the search box.\n","example":true}},"title":"SearchField"}},"text_match_type":{"type":"string","description":"When a search profile has multiple fields defined, this parameter determines how the representative text match score of a product is calculated.\n\n- `max_score (Default)`: In this mode, the products's representative score is simply the highest score from any single matching field. The field weights are used only as a tie-breaker if two products have the exact same highest score. This mode prioritizes the quality of the match in the single best-matching field.\n- `max_weight`: This mode uses the score from the matching field that has the highest weight. This means a partial, lower-quality match on a heavily weighted field (e.g., name) can be prioritized over a perfect match on a lower-weighted field (e.g., description). This mode prioritizes matches in the most important fields, regardless of match quality.\n- `sum_score`: This mode calculates a holistic score by summing the weighted scores from all matching fields. Its advantage is that it rewards products that match a query across multiple attributes. However, it carries the risk that a product with many weak, partial matches across several low-weighted fields could outrank a product with a single strong, perfect match in a high-weighted field.\n","enum":["max_score","max_weight","sum_score"],"example":"max_score","title":"TextMatchType"},"filters":{"type":"array","description":"Optional list of filter expressions to apply to search results. Multiple filters in the array are combined using OR logic (records matching filter1 || filter2 || ... filterN).\nTo combine conditions with AND logic, include multiple conditions within a single filter string (e.g., \"meta.search.categories.lvl1:=`All Products > Mens Shoes` && meta.display_price.without_tax.float_price:>100\").\nThese profile-level filters are ANDed with any filters provided in the search request via the filter_by parameter, resulting in: (profile_filter1 || profile_filter2 || ... profile_filterN) && request_filters.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"exclusions":{"type":"array","description":"A collection of exclusion expressions to apply to search results. Multiple exclusions in the array are combined using OR logic (records matching exclusion1 || exclusion2 || ... exclusionN).","x-go-type-skip-optional-pointer":true,"items":{"type":"string","example":"meta.search.categories.lvl1:=`All Products > Mens Shoes`","minLength":1}},"boosts":{"type":"array","items":{"type":"object","description":"Defines a boosting rule that assigns a score to products matching a specific field value.","required":["condition","weight"],"properties":{"condition":{"type":"string","description":"A filter expression used to identify a subset of products for boosting. This follows the standard filter_by syntax.\n\nIt can be a simple condition like `meta.search.nodes.name:=\\`Electronics\\`` or complex like `meta.search.nodes.name:=\\`Electronics\\` && extensions.products(Details).brand:=Nike`.\n","minLength":1,"example":"meta.search.nodes.name:=\\`Electronics\\`"},"weight":{"type":"integer","description":"A numerical value representing the boost intensity. Products matching the criteria are assigned this value. Higher weights will cause products to appear earlier in the results.\n\n**Impact of Weights:**\n* **Boost (Positive):** Pushes products to the top.\n* **No affect (Zero):** Has no affect. Treated the same as products that match no rules.\n* **Bury (Negative):** Pushes products to the bottom.\n\n**Rule Evaluation:** The system uses \"Short-circuit\" evaluation. The engine stops at the **first matching rule**.\nThis means the weight of the first matching rule will be used as the product weight to sort the results.\nIf no rules match, the product is assigned a weight of `0`.\n","example":5}},"title":"SearchBoostRule"},"x-go-type-skip-optional-pointer":true},"prefix":{"type":"boolean","description":"Profile-level default for prefix (partial match) behavior on the last query token. When true, the last word in the query is treated as a prefix for all fields that do not have an explicit per-field prefix value. For example, a search request for \"red app\" matches \"red apple\". When false, the last word must match exactly. If omitted, default of true applies. Per-field prefix values override this setting.\nThe primary use case is to show results as the user is typing in the search box.\n","example":true},"typo_tolerance":{"type":"object","nullable":true,"description":"Optional typo tolerance configuration applied at search time.\nAll fields are optional; defaults are noted on each field.\n","properties":{"num_typos":{"type":"integer","description":"Profile-level default for the maximum number of typographical errors\n[Damerau-Levenshtein distance](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) allowed when matching any field.\nAccepted values: 0 (exact match only), 1, or 2.\nPer-field `num_typos` values override this setting. If omitted, default of 2 applies.\n\nFor example, a search request for \"red appla\" matches \"red apple\" with a `num_typos` of 1.\n\n**`num_typos` is an upper bound, not a guarantee.** The number of corrections actually\napplied to a query token is also capped by its length via\n`min_len_to_allow_single_character_correction` (default 4) and\n`min_len_to_allow_two_character_correction` (default 7): a token shorter than the\nsingle-character threshold gets no correction at all, and a token shorter than the\ntwo-character threshold is corrected by at most one character — even when `num_typos` is 2.\nSee those two fields for details.\n","minimum":0,"maximum":2,"example":1},"min_len_to_allow_single_character_correction":{"type":"integer","description":"Minimum query-token length required before a single-character typo correction is attempted. This works together with `num_typos`: a token shorter than this length receives no typo correction at all, regardless of `num_typos`. For example, when set to 4, a search for \"appla\" will match \"apple\", but a search for \"apa\" will not match \"app\" because the length of \"apa\" is 3.\nDefault: 4.\n","minimum":1,"example":3},"min_len_to_allow_two_character_correction":{"type":"integer","description":"Minimum query-token length required before a two-character typo correction is attempted. This works together with `num_typos`: even when `num_typos` is 2, a token shorter than this length is corrected by at most one character (and a token shorter than `min_len_to_allow_single_character_correction` is not corrected at all). For example, with the default of 7, the 7-character query \"monetar\" can be corrected to \"monitor\" (two corrections), but a 6-character query with two mistakes cannot.\nDefault: 7\n","minimum":1,"example":7},"typo_tokens_threshold":{"type":"integer","description":"Typo-corrected query variations are only generated if the number of exact results\nfound is fewer than this value. Set to 0 to disable typo tolerance entirely.\nFor example, when set to 5 and the search result only has 3 results, the search engine will apply typo correction to try to return 5 or more results.\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_threshold":{"type":"integer","description":"For multi-word queries, tokens are progressively dropped if the number of results\nis fewer than this value. Set to 0 to disable token dropping.\n\nFor example, when set to 5 and the search result only has 3 results for \"red apple\" search,\nthe search engine will drop the last token \"apple\" and find more results with just by searching for \"red\".\n\nDefault: 1\n","minimum":0,"example":1},"drop_tokens_mode":{"type":"string","description":"Controls the direction in which tokens are dropped from a multi-word query when\nresults fall below drop_tokens_threshold.\n- `right_to_left` (default): drops tokens from the right end of the query first.\n- `left_to_right`: drops tokens from the left end first.\n- `both_sides:N`: drops from both ends, limited to queries of N tokens or fewer\n  (e.g. `both_sides:3` applies only to queries with 3 or fewer tokens).\n","example":"right_to_left"},"enable_typos_for_numerical_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that are purely numeric (every character is a digit, e.g. \"98765\"). Such a token must then match exactly.\nDefault: true\n","example":true},"enable_typos_for_special_char_tokens":{"type":"boolean","description":"When false, typo tolerance is disabled for query tokens that contain at least one non-alphanumeric character\n(any character outside `a-z`, `A-Z`, `0-9`), forcing such tokens to match exactly.\nUseful for keeping product codes / SKUs precise.\n\nTokens like `abc-123`, `abc-def`, `123-456`, and `v1.2.0` are affected;\na plain alphanumeric token like `abc123` is not.\n\nNote: the special character must be indexed on the field (via `symbols_to_index`);\notherwise the search engine removes the special characters from tokens\n(e.g. a token like v1.2.0 becomes v120) and it no longer qualifies.\n\nDefault: true\n","example":true},"split_join_tokens":{"type":"string","description":"Controls whether compound words and multi-word phrases are treated as equivalent during search.\nFor example, a query for \"nonstick\" may also match \"non stick\", and vice versa.\n- `fallback` (default): tries the original query form first; falls back to split/joined variants if results are insufficient.\n- `always`: always generates both split and joined token variants alongside the original query.\n- `off`: disables split/join token handling.\n","enum":["fallback","always","off"],"example":"fallback"}},"title":"TypoTolerance"},"synonym_settings":{"type":"object","nullable":true,"description":"Optional synonym tuning applied at search time. These settings control how synonym\nmatches are ranked and how query tokens are resolved against the synonym sets attached\nto the search profile. All fields are optional; defaults are noted on each field.\nThey only have an observable effect when synonym sets are attached to the resolved profile.\n","properties":{"demote_synonym_match":{"type":"boolean","description":"When true, results matched via a synonym are ranked below direct (non-synonym) matches. When false, synonym matches and direct matches are ranked equally.\nDefault: false\n","example":true},"synonym_resolution_allowed_on_prefix":{"type":"boolean","description":"When true, an incomplete (prefix) query token can resolve to a synonym, i.e. synonym\nexpansion is attempted on prefix tokens.\n\n**This is not the same as the `prefix` setting.** The `prefix` setting treats only the\n**last** word of the query as a prefix; `synonym_resolution_allowed_on_prefix` applies\nprefix matching at **every** token position when looking words up in the synonym sets —\nthere is no last-token special-casing.\n\n**Exact matches always win.** A query token that exactly equals a synonym key resolves\nregardless of this flag; the prefix behavior only affects the fuzzy fallback for tokens\nwith no exact synonym-key match. It composes with\n`number_of_typos_allowed_when_resolving_synonyms`, which governs typo tolerance during\nthe prefix/fuzzy lookup.\n\nWorked example (synonym keys `red`, `apple`, `apparel`):\n- `red app`: `red` matches exactly; `app` prefix-matches both `apple` and `apparel` — both expand.\n- `re app`: `re` prefix-matches `red` **and** `app` prefix-matches `apple`/`apparel` — both expand.\n  The regular `prefix` setting would only treat the last word (`app`) as a prefix; here every\n  position is prefix-matched.\n\nDefault: false\n","example":true},"number_of_typos_allowed_when_resolving_synonyms":{"type":"integer","description":"Number of typos allowed when resolving synonyms. Enables fuzzy synonym matching\nso that a misspelled query term can still trigger a synonym expansion for the\nsynonym sets attached to the search profile.\nAccepted values: 0 (exact synonym match only, default), 1, or 2.\n","minimum":0,"maximum":2,"example":0}},"title":"SynonymSettings"},"synonym_sets":{"type":"array","description":"Optional list of synonym set IDs to apply at search time. Each synonym set must exist and must have been synced to the search engine at least once. Organization-level search profiles may only reference organization-level synonym sets. Store-level search profiles may reference organization-level and same-store synonym sets.\n","x-go-type-skip-optional-pointer":true,"items":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}},"force_use_default_price_for_faceting_and_sorting":{"type":"boolean","description":"When set to true, the default price is used for faceting and sorting for segmented catalogs even if the catalog rule has a supported price book.","default":false,"example":true}},"title":"SearchProfileAttributes"},"meta":{"type":"object","required":["default","owner"],"properties":{"default":{"type":"boolean","description":"Whether this is the default search profile.","example":true},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"}},"title":"SearchProfileMeta"}},"title":"SearchProfile"}},"title":"SearchProfileResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"403":{"description":"Permission denied - search profile owned by the organization","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"404":{"description":"Search profile not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update stopword set

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update stopword set"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/catalogs/search/stopword-sets/{stopword_set_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update the stopwords in an existing stopwords set. The locale cannot be changed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"stopword_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the stopword set","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"StopwordSetID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_stopword_set`.","example":"catalog_search_stopword_set","enum":["catalog_search_stopword_set"],"title":"StopwordSetType"},"attributes":{"type":"object","required":["stopwords"],"properties":{"stopwords":{"type":"array","description":"The replacement list of stopwords. Must contain at least one entry.","items":{"type":"string"},"minItems":1,"example":["the","a","an"]}},"title":"UpdateStopwordSetAttributes"}}}},"title":"UpdateStopwordSetRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully updated stopword set","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the stopword set.","type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_stopword_set`.","example":"catalog_search_stopword_set","enum":["catalog_search_stopword_set"],"title":"StopwordSetType"},"attributes":{"type":"object","required":["stopwords"],"properties":{"locale":{"type":"string","description":"[ISO 639 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for the stopwords set. Omit or pass null for the default set. At most one stopwords set per locale is allowed.\n","example":"en"},"stopwords":{"type":"array","description":"The list of stopwords.","items":{"type":"string"},"minItems":1,"example":["the","a","an","is"]}},"title":"StopwordSetAttributes"},"meta":{"type":"object","required":["created_at","updated_at","owner","sync_status"],"properties":{"created_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was created.","example":"2026-03-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was last updated.","example":"2026-03-05T12:00:00Z"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"},"sync_status":{"type":"string","description":"The sync status of the stopword set.","enum":["pending_sync","synced","sync_failed","pending_delete"],"example":"pending_sync","x-go-type":"model.SyncStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}},"last_synced_at":{"type":"string","format":"date-time","description":"The date and time the stopword set was last successfully synced.","example":"2026-03-05T12:01:00Z"}},"title":"StopwordSetMeta"}},"title":"StopwordSet"}},"title":"StopwordSetResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"404":{"description":"Stopword set not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update synonym set

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update synonym set"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/catalogs/search/synonym-sets/{synonym_set_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a synonym set by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"synonym_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique ID of the synonym set","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"SynonymSetID"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","format":"uuid","example":"8fccaa19-dba9-4621-8d11-31a222a68c7c","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_synonym_set`.","example":"catalog_search_synonym_set","enum":["catalog_search_synonym_set"],"title":"SynonymSetType"},"attributes":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name for the synonym set.","example":"Apparel terms"},"items":{"type":"array","description":"The synonym items in this set.","items":{"type":"object","required":["id","synonyms"],"properties":{"id":{"type":"string","description":"Unique identifier for the synonym item within the set. Alphanumeric, hyphen, and underscore only.","pattern":"^[a-zA-Z0-9_-]+$","example":"footwear-terms","x-go-name":"ID"},"synonyms":{"type":"array","description":"List of synonym terms.","items":{"type":"string"},"minItems":1,"example":["sneakers","trainers","running shoes"]},"root":{"type":"string","description":"Makes this a one-way synonym. Searches for root also match synonyms, but not vice versa.","example":"jacket"},"locale":{"type":"string","description":"[ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for this synonym item.\n","example":"en"},"symbols_to_index":{"type":"array","description":"Symbols to index for this synonym item. Each element must be exactly one character.","items":{"type":"string","minLength":1,"maxLength":1},"example":["-"],"x-go-type-skip-optional-pointer":true}},"title":"SynonymSetItem"},"minItems":1}},"title":"UpdateSynonymSetAttributes"}}}},"title":"UpdateSynonymSetRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully updated synonym set","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier for the synonym set.","type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","x-go-name":"ID"},"type":{"type":"string","description":"Represents the type of object being returned. Always `catalog_search_synonym_set`.","example":"catalog_search_synonym_set","enum":["catalog_search_synonym_set"],"title":"SynonymSetType"},"attributes":{"type":"object","required":["name","items"],"properties":{"name":{"type":"string","description":"Human-readable name for the synonym set.","example":"Apparel terms"},"items":{"type":"array","description":"The synonym items in this set.","items":{"type":"object","required":["id","synonyms"],"properties":{"id":{"type":"string","description":"Unique identifier for the synonym item within the set. Alphanumeric, hyphen, and underscore only.","pattern":"^[a-zA-Z0-9_-]+$","example":"footwear-terms","x-go-name":"ID"},"synonyms":{"type":"array","description":"List of synonym terms.","items":{"type":"string"},"minItems":1,"example":["sneakers","trainers","running shoes"]},"root":{"type":"string","description":"Makes this a one-way synonym. Searches for root also match synonyms, but not vice versa.","example":"jacket"},"locale":{"type":"string","description":"[ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for this synonym item.\n","example":"en"},"symbols_to_index":{"type":"array","description":"Symbols to index for this synonym item. Each element must be exactly one character.","items":{"type":"string","minLength":1,"maxLength":1},"example":["-"],"x-go-type-skip-optional-pointer":true}},"title":"SynonymSetItem"},"minItems":1}},"title":"SynonymSetAttributes"},"meta":{"type":"object","required":["created_at","updated_at","owner","sync_status"],"properties":{"created_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was created.","example":"2026-03-05T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was last updated.","example":"2026-03-05T12:00:00Z"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"organization","enum":["organization","store"],"x-go-type":"tenancy.Owner","x-go-type-import":{"path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/tenancy"},"title":"ResourceOwner"},"sync_status":{"type":"string","description":"The sync status of the synonym set.","enum":["pending_sync","synced","sync_failed","pending_delete"],"example":"pending_sync","x-go-type":"model.SyncStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/ncl-projects/paragon/catalog-search.svc/internal/domain/model"}},"last_synced_at":{"type":"string","format":"date-time","description":"The date and time the synonym set was last successfully synced.","example":"2026-03-05T12:01:00Z"}},"title":"SynonymSetMeta"}},"title":"SynonymSet"}},"title":"SynonymSetResponse"}}}},"400":{"description":"Bad request - invalid parameters","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"404":{"description":"Synonym set not found","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Currency

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Currency"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/currencies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a currency.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"title":"Request.CreateCurrencies","type":"object","properties":{"data":{"required":["type","code","exchange_rate","format","decimal_point","thousand_separator","decimal_places","default","enabled"],"type":"object","properties":{"code":{"description":"Specifies the currency code. Example YEN.","type":"string","example":"GBP","maxLength":3,"minLength":3},"decimal_places":{"description":"Indicates how many decimal places the currency is formatted to.","type":"number","example":2,"minimum":0},"decimal_point":{"description":"Indicates the decimal point character.","type":"string","example":"."},"default":{"description":"Specifies whether this is the default currency or not. Either `true` or `false`.","type":"boolean","example":true},"enabled":{"description":"Specifies if this currency is available for products. Either `true` or `false`.","type":"boolean","example":true},"exchange_rate":{"description":"Specifies the exchange rate from the default currency.","type":"number","example":1,"minimum":0},"format":{"description":"Specifies how the price currency is displayed. For example, \"¥{price}\".","type":"string","example":"£{price}"},"thousand_separator":{"description":"Indicates the thousand separator character.","type":"string","example":","},"type":{"description":"Represents the type represents the object being returned.","type":"string","example":"currency"}},"title":"Data.CreateCurrencies"}}},{"example":[{"data":{"code":"GBP","decimal_places":2,"decimal_point":".","default":true,"enabled":true,"exchange_rate":1,"format":"£{price}","thousand_separator":",","type":"currency"}}]}]},"examples":{"GBP":{"value":{"data":{"code":"GBP","decimal_places":2,"decimal_point":".","default":true,"enabled":true,"exchange_rate":1,"format":"£{price}","thousand_separator":",","type":"currency"}}},"USD":{"value":{"data":{"code":"USD","decimal_places":2,"decimal_point":".","default":true,"enabled":true,"exchange_rate":1,"format":"${price}","thousand_separator":",","type":"currency"}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"id":{"description":"The unique identifier for this currency.","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0","type":"string"},"type":{"description":"Represents the type represents the object being returned.","example":"currency","type":"string"},"code":{"description":"Specifies the currency code. For example, YEN.","example":"GBP","type":"string"},"exchange_rate":{"description":"Specifies the exchange rate from the default currency.","example":1,"type":"number"},"format":{"description":"Specifies how the price currency is displayed. For example, \"£{price}\".","example":"£{price}","type":"string"},"decimal_point":{"description":"Indicates the decimal point character.","example":".","type":"string"},"thousand_separator":{"description":"Indicates the thousand separator character.","example":",","type":"string"},"decimal_places":{"description":"Indicates how many decimal places the currency is formatted to.","example":2,"type":"number"},"default":{"description":"Specifies whether this is the default currency or not. Either `true` or `false`.","example":true,"type":"boolean"},"enabled":{"description":"Specifies if this currency is available for products. Either `true` or `false`.","example":true,"type":"boolean"},"links":{"type":"object","properties":{"self":{"description":"Specifies the URL of this currency.","type":"string"}},"title":"SelfLink"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"Indicates the creation date of this currency.","type":"string","example":"2023-11-07T23:04:18.845Z"},"updated_at":{"description":"Indicates the updated date of this currency.","example":"2023-11-07T23:04:18.845Z"}},"title":"Timestamps"},"owner":{"description":"Indicates whether the owner is store or org.","example":"store","type":"string"}},"title":"Response.Meta.Currency"}},"title":"Response.Currency"}}}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":400,"title":"Currency already exists","detail":"The specified currency code already exists"}]}}}},"422":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":422,"title":"Currency limit reached","detail":"You have reached the maximum allowed currency limit of 10"}]}}}}}}
>
  
</StatusCodes>

---

## Currencies Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/currencies/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Currencies Introduction"}
>
</Heading>

In your store, you can display prices to customers in their local currency. You can configure up to ten currencies per store.

Configure currencies only for the locales in which you do business, and select one of the currencies to be the default currency. If a default currency is not selected, the store uses the United States Dollar (USD).

After a customer selects a locale, the product prices in the catalog, carts, and orders are displayed in the currency for that locale. Order totals and taxes are calculated in the same currency. You cannot have a cart or order where product prices are in mixed currencies.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: 
  
    URL: [https://elasticpath.com](https://elasticpath.com)
  

  
    License
  
    MIT

---

## Currencies

:::caution

- There is a hard limit of 10 currencies per store.

:::

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Delete a Currency

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Currency"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/currencies/{currencyID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a currency.

:::caution

- You can’t delete a default currency.

:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"currencyID","in":"path","description":"The ID for the Currency to delete.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":400,"title":"Bad Request","detail":"The request was invalid"}]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":404,"title":"Currency not found","detail":"The requested currency could not be found"}]}}}}}}
>
  
</StatusCodes>

---

## Get a Currency

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Currency"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/currencies/{currencyID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch a currency by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"currencyID","in":"path","description":"The ID for the requested currency.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"id":{"description":"The unique identifier for this currency.","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0","type":"string"},"type":{"description":"Represents the type represents the object being returned.","example":"currency","type":"string"},"code":{"description":"Specifies the currency code. For example, YEN.","example":"GBP","type":"string"},"exchange_rate":{"description":"Specifies the exchange rate from the default currency.","example":1,"type":"number"},"format":{"description":"Specifies how the price currency is displayed. For example, \"£{price}\".","example":"£{price}","type":"string"},"decimal_point":{"description":"Indicates the decimal point character.","example":".","type":"string"},"thousand_separator":{"description":"Indicates the thousand separator character.","example":",","type":"string"},"decimal_places":{"description":"Indicates how many decimal places the currency is formatted to.","example":2,"type":"number"},"default":{"description":"Specifies whether this is the default currency or not. Either `true` or `false`.","example":true,"type":"boolean"},"enabled":{"description":"Specifies if this currency is available for products. Either `true` or `false`.","example":true,"type":"boolean"},"links":{"type":"object","properties":{"self":{"description":"Specifies the URL of this currency.","type":"string"}},"title":"SelfLink"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"Indicates the creation date of this currency.","type":"string","example":"2023-11-07T23:04:18.845Z"},"updated_at":{"description":"Indicates the updated date of this currency.","example":"2023-11-07T23:04:18.845Z"}},"title":"Timestamps"},"owner":{"description":"Indicates whether the owner is store or org.","example":"store","type":"string"}},"title":"Response.Meta.Currency"}},"title":"Response.Currency"}}}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":400,"title":"Bad Request","detail":"The request was invalid"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":401,"title":"Unauthorized"}]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":404,"title":"Currency not found","detail":"The requested currency could not be found"}]}}}}}}
>
  
</StatusCodes>

---

## Get all Currencies

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Currencies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/currencies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch all currencies.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","style":"form","explode":true,"schema":{"type":"string","example":"0"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","style":"form","explode":true,"schema":{"type":"string","example":"10"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"The unique identifier for this currency.","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0","type":"string"},"type":{"description":"Represents the type represents the object being returned.","example":"currency","type":"string"},"code":{"description":"Specifies the currency code. For example, YEN.","example":"GBP","type":"string"},"exchange_rate":{"description":"Specifies the exchange rate from the default currency.","example":1,"type":"number"},"format":{"description":"Specifies how the price currency is displayed. For example, \"£{price}\".","example":"£{price}","type":"string"},"decimal_point":{"description":"Indicates the decimal point character.","example":".","type":"string"},"thousand_separator":{"description":"Indicates the thousand separator character.","example":",","type":"string"},"decimal_places":{"description":"Indicates how many decimal places the currency is formatted to.","example":2,"type":"number"},"default":{"description":"Specifies whether this is the default currency or not. Either `true` or `false`.","example":true,"type":"boolean"},"enabled":{"description":"Specifies if this currency is available for products. Either `true` or `false`.","example":true,"type":"boolean"},"links":{"type":"object","properties":{"self":{"description":"Specifies the URL of this currency.","type":"string"}},"title":"SelfLink"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"Indicates the creation date of this currency.","type":"string","example":"2023-11-07T23:04:18.845Z"},"updated_at":{"description":"Indicates the updated date of this currency.","example":"2023-11-07T23:04:18.845Z"}},"title":"Timestamps"},"owner":{"description":"Indicates whether the owner is store or org.","example":"store","type":"string"}},"title":"Response.Meta.Currency"}},"title":"Response.Currency"}}}}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":400,"title":"Bad Request","detail":"The request was invalid"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":401,"title":"Unauthorized"}]}}}}}}
>
  
</StatusCodes>

---

## Update a Currency

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Currency"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/currencies/{currencyID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a currency.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"currencyID","in":"path","description":"The ID for the requested currency.","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"description":"","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{"title":"Data.UpdateCurrencies","type":"object","properties":{"default":{"description":"Specifies whether this is the default currency or not. Either `true` or `false`.","type":"boolean","example":true}}}},"title":"Request.UpdateCurrencies"},{"example":[{"data":{"default":true}}]}]},"examples":{"default":{"value":{"data":{"default":true}}}}}},"required":false}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"data":{}},"title":"Response.Data"},{"properties":{"data":{"type":"object","properties":{"id":{"description":"The unique identifier for this currency.","example":"0c45e4ec-26e0-4043-86e4-c15b9cf985a0","type":"string"},"type":{"description":"Represents the type represents the object being returned.","example":"currency","type":"string"},"code":{"description":"Specifies the currency code. For example, YEN.","example":"GBP","type":"string"},"exchange_rate":{"description":"Specifies the exchange rate from the default currency.","example":1,"type":"number"},"format":{"description":"Specifies how the price currency is displayed. For example, \"£{price}\".","example":"£{price}","type":"string"},"decimal_point":{"description":"Indicates the decimal point character.","example":".","type":"string"},"thousand_separator":{"description":"Indicates the thousand separator character.","example":",","type":"string"},"decimal_places":{"description":"Indicates how many decimal places the currency is formatted to.","example":2,"type":"number"},"default":{"description":"Specifies whether this is the default currency or not. Either `true` or `false`.","example":true,"type":"boolean"},"enabled":{"description":"Specifies if this currency is available for products. Either `true` or `false`.","example":true,"type":"boolean"},"links":{"type":"object","properties":{"self":{"description":"Specifies the URL of this currency.","type":"string"}},"title":"SelfLink"},"meta":{"type":"object","properties":{"timestamps":{"type":"object","properties":{"created_at":{"description":"Indicates the creation date of this currency.","type":"string","example":"2023-11-07T23:04:18.845Z"},"updated_at":{"description":"Indicates the updated date of this currency.","example":"2023-11-07T23:04:18.845Z"}},"title":"Timestamps"},"owner":{"description":"Indicates whether the owner is store or org.","example":"store","type":"string"}},"title":"Response.Meta.Currency"}},"title":"Response.Currency"}}}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":400,"title":"Bad Request","detail":"The request was invalid"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":401,"title":"Unauthorized"}]}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An application-specific error code.","example":"1"},"detail":{"type":"string"},"status":{"type":"integer","example":400},"title":{"type":"string"}}}}},"title":"Response.Error"},"example":{"errors":[{"status":404,"title":"Currency not found","detail":"The requested currency could not be found"}]}}}}}}
>
  
</StatusCodes>

---

## Create a File

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a File"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/files"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a File

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"description":"Indicates the file you want to upload.","type":"string","format":"binary","example":"UploadFile"},"file_location":{"description":"Use this parameter to reference a file stored at a specific location. This must be the URL that points to an image file.","type":"string","example":"@/path/to/file.jpg"}}},"examples":{"image_url":{"summary":"Image URL","value":{"file_location":"https://my.example.com/images/abc.png"}},"upload_image":{"summary":"Upload Image","value":{"file":"@path/to/file"}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"properties":{"id":{"description":"The unique identifier for this file.","type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}},"title":"FileMeta"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://https://euwest.api.elasticpath.com//v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}},"title":"Links"},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"}},"title":"FileLink"}},"title":"File"}}},"examples":{"default":{"value":{"data":{"type":"file","id":"f8cf26b3-6d38-4275-937a-624a83994702","link":{"href":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"file_name":"f6669358-85db-4367-9cde-1deb77acb5f4.png","mime_type":"image/png","file_size":110041,"meta":{"dimensions":{"width":1000,"height":1000},"timestamps":{"created_at":"2018-03-13T13:45:21.673Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/files/f8cf26b3-6d38-4275-937a-624a83994702"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"file-location-invalid":{"value":{"errors":[{"title":"file_location invalid","status":422,"detail":"@/path/to/file.jpg is not a valid URL"}]}},"file-not-uploaded":{"value":{"errors":[{"title":"Validation Failed","status":400,"detail":"You have not supplied a file to store"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"file-location-invalid":{"value":{"errors":[{"title":"file_location invalid","status":422,"detail":"@/path/to/file.jpg is not a valid URL"}]}},"file-not-uploaded":{"value":{"errors":[{"title":"Validation Failed","status":400,"detail":"You have not supplied a file to store"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":500,"title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a File

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a File"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/files/{fileID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a File

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"fileID","description":"The unique identifier of the file you want to delete.","in":"path","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"file-location-invalid":{"value":{"errors":[{"title":"Permission denied","status":403,"detail":"You are trying to remove a file outside of the tenancy"}]}}}}}},"404":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"file-not-found":{"value":{"errors":[{"title":"Resource Not Found","status":404,"detail":"The resource you are requesting does not exist"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":500,"title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Files Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/files/files.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Files Introduction"}
>
</Heading>

Products are the items or services that you might want to sell in your store. In Product Experience Manager, products can also have associated rich media assets, such as product images or a file containing additional product details. You can do this using the Files API.

 Once you have created your files, you associate the files with your products using the [Create Product-File Relationships API](/docs/api/pxm/products/create-product-file-relationships).

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Files

You can upload image files or URLs by using `multipart/form-data` as the content type header. For example, `"Content-Type: multipart/form-data" \`. Commerce supports the following file types.

| File Extension | Description |
| --- | --- |
| .gif | Graphics Interchange Format (GIF) |
| .jpg/jpeg | Joint Photographic Experts Group (JPEG) format |
| .png | Portable graphics format  |
| .webp | Web picture format |
| .mp4 | Moving Picture Experts Group (MPEG) format |
| .mov | QuickTime Movie format |
| .pdf | Portable Document Format |
| .usdz | Universal Scene Description Format |
| .glb | Global File format |
| .jp2 | Compressed bitmap image saved in Joint Photographic Experts Group (JPEG) format |
| .jxr | Extended range for Joint Photographic Experts Group (JPEG) format |
| .aac | Advanced Audio Coding (AAC) format |
| .vrml | Virtual Reality Modelling Language (VRML) format  |
| .doc(x)  | Microsoft Word Open XML format |
| .ppt(x) | Microsoft PowerPoint Open XML format |
| .xls(x) | Microsoft Excel Open XML format |

By default, the maximum file size is 8MB. If you need to support larger file sizes, contact your Elastic Path representative. Alternatively, store files somewhere else and reference them.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Get a File

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a File"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/files/{fileID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a File

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"fileID","description":"The unique identifier for a file.","in":"path","required":true,"style":"simple","schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"properties":{"id":{"description":"The unique identifier for this file.","type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}},"title":"FileMeta"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://https://euwest.api.elasticpath.com//v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}},"title":"Links"},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"}},"title":"FileLink"}},"title":"File"}}},"examples":{"default":{"value":{"data":{"type":"file","id":"f8cf26b3-6d38-4275-937a-624a83994702","link":{"href":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"file_name":"f6669358-85db-4367-9cde-1deb77acb5f4.png","mime_type":"image/png","file_size":110041,"meta":{"dimensions":{"width":1000,"height":1000},"timestamps":{"created_at":"2018-03-13T13:45:21.673Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/files/f8cf26b3-6d38-4275-937a-624a83994702"}}}}}}}},"404":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"file-not-found":{"value":{"errors":[{"title":"Resource Not Found","status":404,"detail":"The resource you are requesting does not exist"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":500,"title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Files

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Files"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/files"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all files.

### Filtering

For general filtering syntax, see [Filtering](/guides/Getting-Started/filtering).

The following operators and attributes are available when filtering on this endpoint.

| Attribute             | Type      | Operators           | Example |
|:----------------------|:----------|:--------------------------|:-------------|
| `id`                  | `string`  | `in`                      | `in(id,file-id-1,file-id-2,file-id-3)` |
| `file_name`           | `string`  | `eq` / `like`             | `eq(file_name, my_image.jpg)` |
| `width`               | `integer` | `gt` / `ge` / `lt` / `le` | `gt(width,200)` |
| `height`              | `integer` | `gt` / `ge` / `lt` / `le` | `lt(height,500)` |
| `file_size`           | `integer` | `gt` / `ge` / `lt` / `le` | `le(file_size,20953)` |

#### Bulk File Retrieval

To retrieve multiple files by their IDs in a single request, use the `in` operator with a comma-separated list of file IDs:

```
GET /v2/files?filter=in(id,06b881bd-f152-4c36-8658-7132a8fab49c,ec73567b-04e8-4000-a11a-7e1407cc2f21)
```

This is more efficient than making separate requests for each file and is recommended for bulk operations.

**Note on invalid IDs**: If any IDs in the filter are missing, malformed, or do not exist in the store, they will be silently ignored. The response will only include files that were successfully found. For example, if you request 5 IDs but only 3 exist, the response will contain 3 files with `total: 3` in the metadata.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"description":"\nFiltering is available for this endpoint. See [Filtering](/docs/api/pxm/files/get-all-files#filtering).\n","name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","example":"eq(file_name,00000000-0000-0000-0000-000000000000.png)"}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","style":"form","explode":true,"schema":{"type":"string","minimum":0,"maximum":10000,"format":"int64","examples":["10"]}},{"name":"page[offset]","in":"query","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","style":"form","explode":true,"schema":{"type":"string","minimum":0,"maximum":10000,"format":"int64","examples":["0"]}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"id":{"description":"The unique identifier for this file.","type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}},"title":"FileMeta"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://https://euwest.api.elasticpath.com//v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}},"title":"Links"},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"}},"title":"FileLink"}},"title":"File"}},"meta":{"properties":{"page":{"type":"object","description":"Contains the results for the entire collection.","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","example":100},"offset":{"description":"The current offset by number of pages.","type":"integer","example":0},"current":{"description":"The current number of pages.","type":"integer","example":1},"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1}}},"results":{"type":"object","description":"Contains the results for the entire collection.","properties":{"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1}}}},"title":"ResultsMeta"},"links":{"type":"object","description":"Links are used to allow you to move between requests.","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":["string","null"],"example":"https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100"},"first":{"description":"Always the first page.","type":["string","null"],"example":"https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100"},"last":{"description":"This is `null` if there is only one page.","type":["string","null"],"example":"https://useast.api.elasticpath.com/v2/files?page[offset]=10&page[limit]=100"}},"title":"ResultsLinks"}}},"examples":{"default":{"value":{"data":[{"type":"file","id":"f8cf26b3-6d38-4275-937a-624a83994702","link":{"href":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"file_name":"f6669358-85db-4367-9cde-1deb77acb5f4.png","mime_type":"image/png","file_size":110041,"meta":{"dimensions":{"width":1000,"height":1000},"timestamps":{"created_at":"2018-03-13T13:45:21.673Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/files/f8cf26b3-6d38-4275-937a-624a83994702"}}],"links":{"self":"https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100&filter=","first":"https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100&filter=","last":null},"meta":{"page":{"limit":100,"offset":0,"current":1,"total":1},"results":{"total":1}}}},"bulk_retrieval":{"summary":"Bulk file retrieval using in() filter","description":"Retrieve multiple files by their IDs in a single request. This is useful for operations like fetching product images for all items in a shopping cart.\n\nExample request: GET /v2/files?filter=in(id,f8cf26b3-6d38-4275-937a-624a83994702,a1b2c3d4-5678-90ab-cdef-1234567890ab)\n","value":{"data":[{"type":"file","id":"f8cf26b3-6d38-4275-937a-624a83994702","link":{"href":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"file_name":"product-image-1.png","mime_type":"image/png","file_size":110041,"public":true,"meta":{"dimensions":{"width":1000,"height":1000},"timestamps":{"created_at":"2018-03-13T13:45:21.673Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/files/f8cf26b3-6d38-4275-937a-624a83994702"}},{"type":"file","id":"a1b2c3d4-5678-90ab-cdef-1234567890ab","link":{"href":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/a1b2c3d4-5678-90ab-cdef-1234567890ab.png"},"file_name":"product-image-2.png","mime_type":"image/png","file_size":95234,"public":true,"meta":{"dimensions":{"width":800,"height":800},"timestamps":{"created_at":"2018-03-14T10:22:15.892Z"}},"links":{"self":"https://useast.api.elasticpath.com/v2/files/a1b2c3d4-5678-90ab-cdef-1234567890ab"}}],"links":{"self":"https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100&filter=in(id,f8cf26b3-6d38-4275-937a-624a83994702,a1b2c3d4-5678-90ab-cdef-1234567890ab)","first":"https://useast.api.elasticpath.com/v2/files?page[offset]=0&page[limit]=100&filter=in(id,f8cf26b3-6d38-4275-937a-624a83994702,a1b2c3d4-5678-90ab-cdef-1234567890ab)","last":null},"meta":{"page":{"limit":100,"offset":0,"current":1,"total":1},"results":{"total":2}}}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"integer","format":"int","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"status":500,"title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create Stock for Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Stock for Product"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/inventories/{product_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Sets the inventory quantity for the specified product. When you take this action, you are choosing to manage the inventory for this product in Commerce.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"properties":{"quantity":{"description":"The amount of inventory available.","type":"integer","example":5}},"title":"InventoryCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. Stock was successfully created for product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","id","total","available","allocated"],"properties":{"id":{"description":"The unique identifier of the product.","type":"string","example":"f976dace-450f-4a5d-8877-d119c5a550a1"},"stock_id":{"description":"The Stock ID of a product, or empty if the product ID matches the Stock ID","type":"string","example":"ce9049af-bba2-4db2-8118-5df5268184c7"},"type":{"description":"The type represents the object being returned. Always `stock`.","type":"string","example":"stock","enum":["stock"],"default":"stock"},"total":{"description":"The total amount of stock we have.","type":"integer","format":"int64","example":100},"available":{"description":"The amount of stock available for purchase.","type":"integer","format":"int64","example":75},"allocated":{"description":"The amount of paid for stock, also known as **reserved**.","type":"integer","format":"int64","example":25},"meta":{"allOf":[{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"Meta"}},"title":"Inventory"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No stock found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete Stock for Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Stock for Product"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/inventories/{product_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the inventory for the specified product. The product inventory is null and is no longer managed by Commerce. If you want to keep managing inventory but have none of the product in stock, set the inventory to `0` instead of deleting the inventory.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. Removes the stock information about the product"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No stock found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Stock for Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Stock for Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/{product_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets the stock for the product matching the specified unique identifier.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns the stock for the given product UUID","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","id","total","available","allocated"],"properties":{"id":{"description":"The unique identifier of the product.","type":"string","example":"f976dace-450f-4a5d-8877-d119c5a550a1"},"stock_id":{"description":"The Stock ID of a product, or empty if the product ID matches the Stock ID","type":"string","example":"ce9049af-bba2-4db2-8118-5df5268184c7"},"type":{"description":"The type represents the object being returned. Always `stock`.","type":"string","example":"stock","enum":["stock"],"default":"stock"},"total":{"description":"The total amount of stock we have.","type":"integer","format":"int64","example":100},"available":{"description":"The amount of stock available for purchase.","type":"integer","format":"int64","example":75},"allocated":{"description":"The amount of paid for stock, also known as **reserved**.","type":"integer","format":"int64","example":25},"meta":{"allOf":[{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"Meta"}},"title":"Inventory"},"meta":{"allOf":[{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"Meta"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No stock found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Single Stock Transaction for Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Single Stock Transaction for Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/{product_uuid}/transactions/{transaction_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the specific transaction with transaction_uuid for product_uuid

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}},{"name":"transaction_uuid","in":"path","description":"The unique identifier of the transaction.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns the stock transaction for the given product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type"],"properties":{"id":{"description":"The unique identifier for the stock transaction.","type":"string","example":"f976dace-450f-4a5d-8877-d119c5a550a1"},"type":{"description":"The type represents the object being returned. Always `stock-transaction`.","type":"string","example":"stock-transaction","enum":["stock-transaction"],"default":"stock-transaction"},"action":{"description":"The type of action performed by this transaction.\n\n- **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n- **decrement** - Use this when you want to remove stock from product inventory.\n\n- **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n- **deallocate** - Use this when you want to deallocate any previously allocated stock.\n","type":"string","enum":["increment","decrement","allocate","deallocate"],"example":"allocate"},"product_id":{"description":"The product identifier that this stock transaction is for.","type":"string","example":"86b84d3e-0a86-43d6-a347-78ba4adacca2"},"quantity":{"description":"The amount of stock affected by the stock transaction.","type":"integer","format":"int64","example":5},"timestamps":{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Transaction"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No stock found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Stock for all Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Stock for all Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all products and their associated stock.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"maximum":10000,"example":10}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"example":100}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. All products and their stock values are returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","id","total","available","allocated"],"properties":{"id":{"description":"The unique identifier of the product.","type":"string","example":"f976dace-450f-4a5d-8877-d119c5a550a1"},"stock_id":{"description":"The Stock ID of a product, or empty if the product ID matches the Stock ID","type":"string","example":"ce9049af-bba2-4db2-8118-5df5268184c7"},"type":{"description":"The type represents the object being returned. Always `stock`.","type":"string","example":"stock","enum":["stock"],"default":"stock"},"total":{"description":"The total amount of stock we have.","type":"integer","format":"int64","example":100},"available":{"description":"The amount of stock available for purchase.","type":"integer","format":"int64","example":75},"allocated":{"description":"The amount of paid for stock, also known as **reserved**.","type":"integer","format":"int64","example":25},"meta":{"allOf":[{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"Meta"}},"title":"Inventory"}},"meta":{"allOf":[{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"Meta"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No stock found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Stock for Multiple Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Stock for Multiple Products"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/inventories/multiple"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns stock for all products matching the supplied unique identifiers.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id"],"properties":{"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock"},"id":{"description":"The unique identifier of the product.","type":"string","format":"uuid","example":"3c78777a-cf09-4b2d-be91-a73acbf9166f"}},"title":"MultipleProducts"}}}},"example":{"data":[{"id":"ebc7652d-bb7d-4359-9a83-78f2998208d9"},{"id":"5334e697-a576-4ac5-8075-ab457dfcaddd"}]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Multiple products and their stock values are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","id","total","available","allocated"],"properties":{"id":{"description":"The unique identifier of the product.","type":"string","example":"f976dace-450f-4a5d-8877-d119c5a550a1"},"stock_id":{"description":"The Stock ID of a product, or empty if the product ID matches the Stock ID","type":"string","example":"ce9049af-bba2-4db2-8118-5df5268184c7"},"type":{"description":"The type represents the object being returned. Always `stock`.","type":"string","example":"stock","enum":["stock"],"default":"stock"},"total":{"description":"The total amount of stock we have.","type":"integer","format":"int64","example":100},"available":{"description":"The amount of stock available for purchase.","type":"integer","format":"int64","example":75},"allocated":{"description":"The amount of paid for stock, also known as **reserved**.","type":"integer","format":"int64","example":25},"meta":{"allOf":[{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"Meta"}},"title":"Inventory"}}}},"example":{"data":[{"id":"ebc7652d-bb7d-4359-9a83-78f2998208d9","type":"stock","total":100,"available":75,"allocated":25},{"id":"5334e697-a576-4ac5-8075-ab457dfcaddd","type":"stock","total":22,"available":18,"allocated":4}]}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No stock found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Stock Transactions for Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Stock Transactions for Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/{product_uuid}/transactions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the transactions recorded for the specified product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"maximum":10000,"example":10}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"example":100}},{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns the stock for the given product","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"allOf":[{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"Meta"},"data":{"type":"array","items":{"required":["type"],"properties":{"id":{"description":"The unique identifier for the stock transaction.","type":"string","example":"f976dace-450f-4a5d-8877-d119c5a550a1"},"type":{"description":"The type represents the object being returned. Always `stock-transaction`.","type":"string","example":"stock-transaction","enum":["stock-transaction"],"default":"stock-transaction"},"action":{"description":"The type of action performed by this transaction.\n\n- **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n- **decrement** - Use this when you want to remove stock from product inventory.\n\n- **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n- **deallocate** - Use this when you want to deallocate any previously allocated stock.\n","type":"string","enum":["increment","decrement","allocate","deallocate"],"example":"allocate"},"product_id":{"description":"The product identifier that this stock transaction is for.","type":"string","example":"86b84d3e-0a86-43d6-a347-78ba4adacca2"},"quantity":{"description":"The amount of stock affected by the stock transaction.","type":"integer","format":"int64","example":5},"timestamps":{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Transaction"}}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Inventories Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/inventory/public_legacy_openapi.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Inventories Introduction"}
>
</Heading>

The Inventory API allows you to manage stock for products at both organization and store levels. 

:::note

This basic version of inventories service does not support multi-location inventory. To access the newer location-aware interface to this service one must pass the following HTTP header when making API requests:

```
  EP-Inventories-Multi-Location: true
```

Please refer to the [Multi-location Inventory API](/docs/api/pxm/inventory_mli) documentation as the interface is not entirely compatible with that described here.

:::

Inventory is the quantity of each product that you have in stock. The inventory service allows you and your business to keep track of inventory, including a transactional historic log. 

Inventory for each product is tracked using the following values:

- **Total**: The amount of product in stock. (Total = Available + Allocated)
- **Available**: The amount of product available in stock minus allocated products. (Available = Total - Allocated)
- **Allocated**: The amount of reserved product in stock.

:::note

In Commerce Manager, you can manage the inventory while creating a new product in Product Experience Manager. Go to **Products** > **Inventory** and you can specify the inventory details (**allocate**, **deallocate**, **increment**, and **decrement**). 

:::

### Order flow

There are three mandatory steps to complete an order in relation to inventory:

1. Added to a cart
2. Checked out
3. Paid
4. Shipped (optional)

#### Unpaid order flow

The following flowchart depicts the process of an unpaid order.

![The order is created from the cart during the checkout process.](/assets/order-flow.png)

#### Payment flow

The following flowchart depicts the process of paying for an order.

![The payment workflow.](/assets/payment-workflow-1.png)

### How stock is managed

Stock is managed as follows:

1. When a customer attempts to add products to a cart, the inventory service checks if there is enough available stock. If there is not enough stock available, you receive a 400 HTTP response with a warning. The response does not describe what products cannot be added, nor does it return how many products are in stock.
2. If a customer successfully adds products to a cart, the customer can checkout to create an unpaid order.
3. A final check on the available stock is performed. 
4. After creating the unpaid order, the payment for an order can be taken. When a customer attempts to pay for an order, the inventory service reserves the stock before the payment is processed internally. At any time before the point of payment, a customer might lose their order, if the customer is slower than everyone else.

    If the payment fails, the temporary stock allocation is removed, and the stock becomes available again for anyone to buy. 

    If the payment succeeds, that stock is still allocated, and the items belong to the customer, unless for any reason they are reallocated before shipment. For example, if the customer cancels, or you realize the order is fraudulent, then you can reallocate the inventory. 
5. Finally, when the order is marked as shipped, that stock is fully decremented. This means the allocation number is reduced, and therefore the total, and the products are no longer in the warehouse.

During split payments, stocks are allocated only if the first transaction for an order is complete. If the transaction fails, the stocks are deallocated. Once the first transaction is complete, the stocks are not allocated for the subsequent transactions as they are already reserved for the order. The stocks are deallocated and return to available when the the order is canceled.

### Implications of the inventories API

- It is possible for more products to be in carts than there are in stock if the `add to cart` request quantity is less than available stocks. For example, when available stocks are 100, a user can add 60 to cart 1 and then 50 to cart 1, or user A can add 80 to cart 1, while user B can add 30 to cart 2.
- It is possible for more products to be checked out than there are in stock if the `add to cart` request quantity is less than the available stocks.
- It is not possible for more stock to be paid for than is in stock.
- It is a race for your customers to pay for an order, and whoever does not pay fast enough, is left disappointed.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Inventory

The Inventory API allows you to manage stock for products at both organization and store levels. Each product keeps a history of inventory transactions, enabling easier stock auditing.

You can specify an initial stock level when you create a product. The stock is set to `0` by default.

:::caution 

You cannot create multiple inventories of the same organization-level product in different stores because no unique stock ID, specific to each store, is currently generated. Hence, when you try to manage inventory of the same product for different stores, you get an invalid product identifier error. 

:::

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Transactions

Methods to allow you to modify and view a products stock via transactions.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Create Stock Transaction on Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Stock Transaction on Product"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/inventories/{product_uuid}/transactions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create Stock Transaction on Product

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["action","type"],"properties":{"product_id":{"description":"The ID of the product to perform the transaction against","type":"string","format":"uuid","example":"b9ad64bd-fc21-4918-b6ec-768809f4a1e9"},"type":{"description":"The type of object being returned. Always `stock-transaction`.","type":"string","enum":["stock-transaction"],"default":"stock-transaction","example":"stock-transaction"},"action":{"description":"The type of action being performed by this transaction.\n\n - **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n - **decrement** - Use this when you want to remove stock from product inventory.\n\n - **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n - **deallocate** - Use this when you want to deallocate any previously allocated stock.\n","type":"string","enum":["increment","decrement","allocate","deallocate"],"example":"allocate"},"quantity":{"description":"The amount of stock affected by the stock transaction.","type":"integer","format":"int64","example":5,"minimum":1}},"title":"TransactionCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Stock was successfully modified for product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type"],"properties":{"id":{"description":"The unique identifier for the stock transaction.","type":"string","example":"f976dace-450f-4a5d-8877-d119c5a550a1"},"type":{"description":"The type represents the object being returned. Always `stock-transaction`.","type":"string","example":"stock-transaction","enum":["stock-transaction"],"default":"stock-transaction"},"action":{"description":"The type of action performed by this transaction.\n\n- **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n- **decrement** - Use this when you want to remove stock from product inventory.\n\n- **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n- **deallocate** - Use this when you want to deallocate any previously allocated stock.\n","type":"string","enum":["increment","decrement","allocate","deallocate"],"example":"allocate"},"product_id":{"description":"The product identifier that this stock transaction is for.","type":"string","example":"86b84d3e-0a86-43d6-a347-78ba4adacca2"},"quantity":{"description":"The amount of stock affected by the stock transaction.","type":"integer","format":"int64","example":5},"timestamps":{"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Transaction"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No stock found"}]}}}}}},"422":{"description":"The request was understood, but could not be processed by the server","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Cannot complete request","status":"422","detail":"Your request could not be completed due to insufficient stock levels"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Import a dataset

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Import a dataset"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/inventories/imports"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Import a dataset

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"multipart/form-data":{"schema":{"type":"object","required":["import_file"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"import_file":{"description":"The JSONL file you want to upload.","type":"string","format":"binary"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The import was started.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["id","type","meta","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","example":"inventories_import","enum":["inventories_import"],"title":"InventoriesImportType"},"attributes":{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.\n- **pending** - Commerce has received the request but is currently busy processing other requests.\n- **started** - Commerce has started processing the job.\n- **success** - The job has successfully completed.\n- **failed** - The job has failed.\n","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"}}},"title":"ImportAttributes"},"meta":{"readOnly":true,"required":["timestamps","records"],"properties":{"timestamps":{"allOf":[{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"records":{"type":"object","description":"You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported. However, this does not mean they are valid objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added.","required":["uploaded","imported"],"properties":{"uploaded":{"type":"object","properties":{"stock":{"description":"The total number of product transactions uploaded.","type":"integer","example":50000}},"required":["stock"]},"imported":{"properties":{"stock":{"description":"The total number of product transactions uploaded.","type":"integer","example":50000}},"required":["stock"]}},"title":"ImportRecords"}},"title":"ImportMeta"}},"title":"Import"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Location

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Location"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/inventories/locations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates an Inventory Location

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["attributes"],"properties":{"type":{"type":"string","enum":["inventory_location"],"example":"inventory_location","title":"InventoryLocationType"},"attributes":{"required":["name","slug"],"properties":{"name":{"type":"string","minLength":3,"maxLength":1024,"example":"Milton Keynes Warehouse"},"external_ref":{"type":"string","minLength":3,"maxLength":1024,"example":"mk-stock-warehouse-walnut-tree"},"slug":{"type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"},"description":{"type":"string","minLength":3,"maxLength":1024,"example":"Southern dispatch location for all inventory"},"address":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","maxLength":1024}},"geolocation":{"type":"object","nullable":true,"description":"The longitude and latitude of a location.","required":["lat","lon"],"properties":{"lat":{"type":"number","format":"double","nullable":false,"example":51.477928},"lon":{"type":"number","format":"double","nullable":false,"example":-0.001545}},"example":{"lat":51.477928,"lon":-0.001545},"title":"GeolocationDetails"}},"title":"LocationAttributes"}},"title":"LocationRequest"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The location was created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["inventory_location"],"example":"inventory_location","title":"InventoryLocationType"},"attributes":{"required":["name","slug"],"properties":{"name":{"type":"string","minLength":3,"maxLength":1024,"example":"Milton Keynes Warehouse"},"external_ref":{"type":"string","minLength":3,"maxLength":1024,"example":"mk-stock-warehouse-walnut-tree"},"slug":{"type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"},"description":{"type":"string","minLength":3,"maxLength":1024,"example":"Southern dispatch location for all inventory"},"address":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","maxLength":1024}},"geolocation":{"type":"object","nullable":true,"description":"The longitude and latitude of a location.","required":["lat","lon"],"properties":{"lat":{"type":"number","format":"double","nullable":false,"example":51.477928},"lon":{"type":"number","format":"double","nullable":false,"example":-0.001545}},"example":{"lat":51.477928,"lon":-0.001545},"title":"GeolocationDetails"}},"title":"LocationAttributes"},"meta":{"type":"object","required":["timestamps"],"properties":{"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"Location"}}},"example":{"data":{"id":"ebc7652d-bb7d-4359-9a83-78f2998208d9","type":"inventory_location","attributes":{"name":"Milton Keynes Warehouse","external_ref":"mk-stock-warehouse-walnut-tree","slug":"milton-keynes-warehouse","description":"Southern dispatch location for all inventory","address":["Troughton Supplies","38 Pipernel Grove","Walnut Tree","MK7 4UL"],"geolocation":{"lat":-90,"lon":180}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create Stock for Product(Inventory_mli)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Stock for Product"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/inventories"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Sets the inventory quantity for the specified product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock","title":"StockType"},"attributes":{"type":"object","properties":{"available":{"type":"integer","format":"int64","example":20},"locations":{"type":"object","additionalProperties":{"type":"object","required":["available"],"properties":{"available":{"type":"integer","format":"int64","example":20}}},"example":{"york_warehouse":{"available":10},"stevenage_warehouse":{"available":20}}}},"title":"StockCreateAttributes"}},"title":"StockCreate"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. Stock was successfully created for product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock","title":"StockType"},"attributes":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30},"locations":{"type":"object","additionalProperties":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30}}},"title":"StockLocations"}},"title":"StockResponseAttributes"},"meta":{"type":"object","required":["stock_id","timestamps"],"properties":{"stock_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"StockMeta"}},"title":"StockResponse"}},"required":["data"]}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create Stock Transaction on Product(Inventory_mli)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Stock Transaction on Product"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/inventories/{product_uuid}/transactions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create Stock Transaction on Product

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","enum":["stock-transaction"],"default":"stock-transaction","example":"stock-transaction","title":"StockTransactionType"},"attributes":{"required":["action","quantity"],"properties":{"product_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"action":{"description":"The type of action being performed by this transaction.\n\n - **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n - **decrement** - Use this when you want to remove stock from product inventory.\n\n - **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n - **deallocate** - Use this when you want to deallocate any previously allocated stock.\n\n - **set** - Use this when you want to set total stock to a specific value.\n","type":"string","enum":["increment","decrement","allocate","deallocate","set"],"example":"allocate","x-go-type":"model.TransactionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"}},"quantity":{"description":"The amount of stock affected by the stock transaction.","type":"integer","format":"int64","example":5,"minimum":0},"location":{"description":"The slug of the location that the transaction should act on.","type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"}},"title":"TransactionCreateAttributes"}},"title":"TransactionCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. Stock was successfully created for product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock-transaction"],"default":"stock-transaction","example":"stock-transaction","title":"StockTransactionType"},"attributes":{"type":"object","required":["action","product_id","quantity"],"properties":{"action":{"description":"The type of action performed by this transaction.\n\n- **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n- **decrement** - Use this when you want to remove stock from product inventory.\n\n- **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n- **deallocate** - Use this when you want to deallocate any previously allocated stock.\n","type":"string","enum":["increment","decrement","allocate","deallocate"],"example":"allocate","x-go-type":"model.TransactionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"}},"product_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"quantity":{"description":"The amount of stock affected by the stock transaction.","type":"integer","format":"int64","example":5},"location":{"description":"The slug of the location that the transaction should act on.","type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"}},"title":"TransactionResponseAttributes"},"meta":{"type":"object","required":["timestamps"],"properties":{"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"TransactionResponse"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"422":{"description":"The request was understood, but could not be processed by the server","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Cannot complete request","status":"422","detail":"Your request could not be completed due to insufficient stock levels"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a Location

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Location"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/inventories/locations/{location_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete an Inventory Location

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"location_uuid","in":"path","description":"The unique identifier of the location.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The location is deleted"}}}
>
  
</StatusCodes>

---

## Delete Stock for Product(Inventory_mli)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Stock for Product"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/inventories/{product_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the inventory for the specified product. The product inventory is null and is no longer managed by Commerce. If you want to keep managing inventory but have none of the product in stock, set the inventory to `0` instead of deleting the inventory.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. Removes the stock information about the product"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get import errors

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get import errors"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/imports/{import_uuid}/errors"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all errors encountered as part of the import. Each error is attributed to a line in the JSONL file 
imported, so for example, if at line 1 in your JSONL you had a stock without locations, there would
be a missing key error for locations.

Errors are also ordered by line number ascending, and can be paginated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"maximum":10000,"example":10}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"example":100}},{"name":"import_uuid","in":"path","description":"The unique identifier of the import.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The import errors are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","example":"inventories_import_error","enum":["inventories_import_error"],"title":"InventoriesImportErrorType"},"meta":{"type":"object","required":["timestamps","error","field","line_number"],"properties":{"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"error":{"type":"string","example":"product name cannot be empty"},"field":{"type":"string","example":"name"},"line_number":{"type":"integer","description":"The line in the imported JSONL file at which the validation error occurred. Starts from 1.","example":123},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"}},"title":"InventoriesImportErrorMeta"}},"title":"InventoriesImportError"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get import

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get import"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/imports/{import_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the import job for the specified ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"maximum":10000,"example":10}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"example":100}},{"name":"import_uuid","in":"path","description":"The unique identifier of the import.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The import is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["id","type","meta","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","example":"inventories_import","enum":["inventories_import"],"title":"InventoriesImportType"},"attributes":{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.\n- **pending** - Commerce has received the request but is currently busy processing other requests.\n- **started** - Commerce has started processing the job.\n- **success** - The job has successfully completed.\n- **failed** - The job has failed.\n","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"}}},"title":"ImportAttributes"},"meta":{"readOnly":true,"required":["timestamps","records"],"properties":{"timestamps":{"allOf":[{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"records":{"type":"object","description":"You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported. However, this does not mean they are valid objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added.","required":["uploaded","imported"],"properties":{"uploaded":{"type":"object","properties":{"stock":{"description":"The total number of product transactions uploaded.","type":"integer","example":50000}},"required":["stock"]},"imported":{"properties":{"stock":{"description":"The total number of product transactions uploaded.","type":"integer","example":50000}},"required":["stock"]}},"title":"ImportRecords"}},"title":"ImportMeta"}},"title":"Import"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a Location

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Location"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/locations/{location_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get an Inventory Location

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"location_uuid","in":"path","description":"The unique identifier of the location.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The location is returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["inventory_location"],"example":"inventory_location","title":"InventoryLocationType"},"attributes":{"required":["name","slug"],"properties":{"name":{"type":"string","minLength":3,"maxLength":1024,"example":"Milton Keynes Warehouse"},"external_ref":{"type":"string","minLength":3,"maxLength":1024,"example":"mk-stock-warehouse-walnut-tree"},"slug":{"type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"},"description":{"type":"string","minLength":3,"maxLength":1024,"example":"Southern dispatch location for all inventory"},"address":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","maxLength":1024}},"geolocation":{"type":"object","nullable":true,"description":"The longitude and latitude of a location.","required":["lat","lon"],"properties":{"lat":{"type":"number","format":"double","nullable":false,"example":51.477928},"lon":{"type":"number","format":"double","nullable":false,"example":-0.001545}},"example":{"lat":51.477928,"lon":-0.001545},"title":"GeolocationDetails"}},"title":"LocationAttributes"},"meta":{"type":"object","required":["timestamps"],"properties":{"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"Location"}}},"example":{"data":{"id":"ebc7652d-bb7d-4359-9a83-78f2998208d9","type":"inventory_location","attributes":{"name":"Milton Keynes Warehouse","external_ref":"mk-stock-warehouse-walnut-tree","slug":"milton-keynes-warehouse","description":"Southern dispatch location for all inventory","address":["Troughton Supplies","38 Pipernel Grove","Walnut Tree","MK7 4UL"],"geolocation":{"lat":-90,"lon":180}}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}}}}
>
  
</StatusCodes>

---

## List Stock

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Stock"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/inventories/multiple"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns stock for all products matching the supplied unique identifiers.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id"],"properties":{"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock"},"id":{"description":"The unique identifier of the product.","type":"string","format":"uuid","example":"3c78777a-cf09-4b2d-be91-a73acbf9166f"}},"title":"MultipleProducts"}}}},"example":{"data":[{"id":"ebc7652d-bb7d-4359-9a83-78f2998208d9"},{"id":"5334e697-a576-4ac5-8075-ab457dfcaddd"}]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Multiple products and their stock values are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock","title":"StockType"},"attributes":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30},"locations":{"type":"object","additionalProperties":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30}}},"title":"StockLocations"}},"title":"StockResponseAttributes"},"meta":{"type":"object","required":["stock_id","timestamps"],"properties":{"stock_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"StockMeta"}},"title":"StockResponse"}}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Stock for Product(Inventory_mli)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Stock for Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/{product_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets the stock for the product matching the specified unique identifier.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns the stock for the given product UUID","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock","title":"StockType"},"attributes":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30},"locations":{"type":"object","additionalProperties":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30}}},"title":"StockLocations"}},"title":"StockResponseAttributes"},"meta":{"type":"object","required":["stock_id","timestamps"],"properties":{"stock_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"StockMeta"}},"title":"StockResponse"}},"required":["data"]}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Single Stock Transaction for Product(Inventory_mli)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Single Stock Transaction for Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/{product_uuid}/transactions/{transaction_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the specific transaction with transaction_uuid for product_uuid

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}},{"name":"transaction_uuid","in":"path","description":"The unique identifier of the transaction.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns the stock transaction for the given product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock-transaction"],"default":"stock-transaction","example":"stock-transaction","title":"StockTransactionType"},"attributes":{"type":"object","required":["action","product_id","quantity"],"properties":{"action":{"description":"The type of action performed by this transaction.\n\n- **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n- **decrement** - Use this when you want to remove stock from product inventory.\n\n- **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n- **deallocate** - Use this when you want to deallocate any previously allocated stock.\n","type":"string","enum":["increment","decrement","allocate","deallocate"],"example":"allocate","x-go-type":"model.TransactionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"}},"product_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"quantity":{"description":"The amount of stock affected by the stock transaction.","type":"integer","format":"int64","example":5},"location":{"description":"The slug of the location that the transaction should act on.","type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"}},"title":"TransactionResponseAttributes"},"meta":{"type":"object","required":["timestamps"],"properties":{"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"TransactionResponse"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Imports

You can import stock positions for up to 50,000 products in a single operation via an import. This is useful for synchronosing external systems with Elastic Path.
The API uses a [**JSONL**](https://jsonlines.org/) file, with one line per product. For each product one specifies the total stock in each location. For example

```
{"data":{"type":"stock","id":"b36ba644-6fdc-49b3-9ebb-410ed34908a8","attributes":{"locations":{"vancouver":{"total":20}}}}}
{"data":{"type":"stock","id":"2e5a4c7b-6f88-4aad-a3c2-4d8b29bc32a4","attributes":{"locations":{"vancouver":{"total":54},"denver":{"total":1},"boston":{"total":20},"portland":{"total":100}}}}}
```

### Characteristics of Inventories Import

The Inventories Import API has the following characteristics:

- The Inventories Import API reads the entire file and then updates the inventory.

- Inventories imports are asynchronous and are processed one at a time. You can continue to send import requests, but these are queued. 

- If a product in an import does not already exist in the inventories database it will be created.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Inventories Introduction(Inventory_mli)

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/inventory/public_openapi.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Inventories Introduction"}
>
</Heading>

The Inventory API allows you to manage stock for products at both organization and store levels. Stock can be optionally managed in [multiple locations](#multi-location-inventories) representing different stores or warehouses.

:::note

This version of the inventories service is not entirely compatible with the [basic version](/docs/api/pxm/inventory) and so must be enabled by setting the following HTTP header when making requests:

```
  EP-Inventories-Multi-Location: true
```

The two systems operate on the same database and may be used interchangeably for stock that does not use multiple locations.

:::

Inventory is the quantity of each product that you have in stock. The inventory service allows you and your business to keep track of inventory, including a transactional historic log. 

Inventory for each product is tracked using the following values:

- **Total**: The amount of product in stock. (Total = Available + Allocated)
- **Available**: The amount of product available in stock minus allocated products. (Available = Total - Allocated)
- **Allocated**: The amount of reserved product in stock.

:::note

In Commerce Manager, you can manage the inventory while creating a new product in Product Experience Manager. Go to **Products** > **Inventory** and you can specify the inventory details (**allocate**, **deallocate**, **increment**, and **decrement**). 

:::

### Order flow

There are three mandatory steps to complete an order in relation to inventory:

1. Added to a cart
2. Checked out
3. Paid
4. Shipped (optional)

#### Unpaid order flow

The following flowchart depicts the process of an unpaid order.

![The order is created from the cart during the checkout process.](/assets/order-flow.png)

#### Payment flow

The following flowchart depicts the process of paying for an order.

![The payment workflow.](/assets/payment-workflow-1.png)

### How stock is managed

Stock is managed as follows:

1. When a customer attempts to add products to a cart, the inventory service checks if there is enough available stock. If there is not enough stock available, you receive a 400 HTTP response with a warning. The response does not describe what products cannot be added, nor does it return how many products are in stock.
2. If a customer successfully adds products to a cart, the customer can checkout to create an unpaid order.
3. A final check on the available stock is performed. 
4. After creating the unpaid order, the payment for an order can be taken. When a customer attempts to pay for an order, the inventory service reserves the stock before the payment is processed internally. At any time before the point of payment, a customer might lose their order, if the customer is slower than everyone else.

    If the payment fails, the temporary stock allocation is removed, and the stock becomes available again for anyone to buy. 

    If the payment succeeds, that stock is still allocated, and the items belong to the customer, unless for any reason they are reallocated before shipment. For example, if the customer cancels, or you realize the order is fraudulent, then you can reallocate the inventory. 
5. Finally, when the order is marked as shipped, that stock is fully decremented. This means the allocation number is reduced, and therefore the total, and the products are no longer in the warehouse.

During split payments, stocks are allocated only if the first transaction for an order is complete. If the transaction fails, the stocks are deallocated. Once the first transaction is complete, the stocks are not allocated for the subsequent transactions as they are already reserved for the order. The stocks are deallocated and return to available when the order is canceled.

### Implications of the inventories API

- It is possible for more products to be in carts than there are in stock if the `add to cart` request quantity is less than available stocks. For example, when available stocks are 100, a user can add 60 to cart 1 and then 50 to cart 1, or user A can add 80 to cart 1, while user B can add 30 to cart 2.
- It is possible for more products to be checked out than there are in stock if the `add to cart` request quantity is less than the available stocks.
- It is not possible for more stock to be paid for than is in stock.
- It is a race for your customers to pay for an order, and whoever does not pay fast enough, is left disappointed.

### Multi-location inventories

If you wish to manage stock in multiple locations you can [create a number of locations](/docs/api/pxm/inventory_mli/create-location) and then when [creating stock inventory](/docs/api/pxm/inventory_mli/create-stock), specify a different stock position for each location.

Then, when adding to cart, one can specify the location that will supply the inventory for that product and the system will manage stock in that location, checking stock levels and allocating and decrementing the correct stock position through the life cycle of the order.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Inventory(Inventory_mli)

The Inventory API allows you to manage stock for products at both organization and store levels. Each product keeps a history of inventory transactions, enabling easier stock auditing.

You can specify an initial stock level when you create a product. The stock is set to `0` by default.

:::caution 

You cannot create multiple inventories of the same organization-level product in different stores because no unique stock ID, specific to each store, is currently generated. Hence, when you try to manage inventory of the same product for different stores, you get an invalid product identifier error. 

:::

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## List import jobs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List import jobs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/imports"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all import jobs.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Inventories API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(location,new-york)"}},{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"maximum":10000,"example":10}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"example":100}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of import jobs is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["id","type","meta","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","example":"inventories_import","enum":["inventories_import"],"title":"InventoriesImportType"},"attributes":{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.\n- **pending** - Commerce has received the request but is currently busy processing other requests.\n- **started** - Commerce has started processing the job.\n- **success** - The job has successfully completed.\n- **failed** - The job has failed.\n","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"}}},"title":"ImportAttributes"},"meta":{"readOnly":true,"required":["timestamps","records"],"properties":{"timestamps":{"allOf":[{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"records":{"type":"object","description":"You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported. However, this does not mean they are valid objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added.","required":["uploaded","imported"],"properties":{"uploaded":{"type":"object","properties":{"stock":{"description":"The total number of product transactions uploaded.","type":"integer","example":50000}},"required":["stock"]},"imported":{"properties":{"stock":{"description":"The total number of product transactions uploaded.","type":"integer","example":50000}},"required":["stock"]}},"title":"ImportRecords"}},"title":"ImportMeta"}},"title":"Import"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List Locations

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Locations"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/locations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Lists all Inventory Locations

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"maximum":10000,"example":10}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Inventories API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(location,new-york)"}},{"description":"Only supported value is `location`. When specified, the results are sorted in ascending order based on the value of the field. For `location`, this means ascending distance from the supplied geolocation. For more information, see [Sorting](/guides/Getting-Started/sorting). For location sorting, `Ep-Geolocation` header must be provided as well.","name":"sort","in":"query","schema":{"type":"string","enum":["location"]}},{"description":"Latitude, Longitude representing current location","name":"Ep-Geolocation","in":"header","schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$"},"example":"49.2847027,-123.1109329"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of locations is returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["inventory_location"],"example":"inventory_location","title":"InventoryLocationType"},"attributes":{"required":["name","slug"],"properties":{"name":{"type":"string","minLength":3,"maxLength":1024,"example":"Milton Keynes Warehouse"},"external_ref":{"type":"string","minLength":3,"maxLength":1024,"example":"mk-stock-warehouse-walnut-tree"},"slug":{"type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"},"description":{"type":"string","minLength":3,"maxLength":1024,"example":"Southern dispatch location for all inventory"},"address":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","maxLength":1024}},"geolocation":{"type":"object","nullable":true,"description":"The longitude and latitude of a location.","required":["lat","lon"],"properties":{"lat":{"type":"number","format":"double","nullable":false,"example":51.477928},"lon":{"type":"number","format":"double","nullable":false,"example":-0.001545}},"example":{"lat":51.477928,"lon":-0.001545},"title":"GeolocationDetails"}},"title":"LocationAttributes"},"meta":{"type":"object","required":["timestamps"],"properties":{"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"Location"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}},"example":{"data":[{"id":"ebc7652d-bb7d-4359-9a83-78f2998208d9","type":"inventory_location","attributes":{"name":"Milton Keynes Warehouse","external_ref":"mk-stock-warehouse-walnut-tree","slug":"milton-keynes-warehouse","description":"Southern dispatch location for all inventory","address":["Troughton Supplies","38 Pipernel Grove","Walnut Tree","MK7 4UL"],"geolocation":{"lat":-90,"lon":180}}}]}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Stock for all Products(Inventory_mli)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Stock for all Products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns all products and their associated stock.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"maximum":10000,"example":10}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Inventories API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(location,new-york)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. All products and their stock values are returned","content":{"application/json":{"schema":{"type":"object","required":["data","links"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock","title":"StockType"},"attributes":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30},"locations":{"type":"object","additionalProperties":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30}}},"title":"StockLocations"}},"title":"StockResponseAttributes"},"meta":{"type":"object","required":["stock_id","timestamps"],"properties":{"stock_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"StockMeta"}},"title":"StockResponse"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Stock Transactions for Product(Inventory_mli)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Stock Transactions for Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/inventories/{product_uuid}/transactions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the transactions recorded for the specified product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"maximum":10000,"example":10}},{"description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","name":"page[limit]","in":"query","required":false,"schema":{"type":"integer","format":"int","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Inventories API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(location,new-york)"}},{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Returns the stock for the given product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock-transaction"],"default":"stock-transaction","example":"stock-transaction","title":"StockTransactionType"},"attributes":{"type":"object","required":["action","product_id","quantity"],"properties":{"action":{"description":"The type of action performed by this transaction.\n\n- **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n- **decrement** - Use this when you want to remove stock from product inventory.\n\n- **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n- **deallocate** - Use this when you want to deallocate any previously allocated stock.\n","type":"string","enum":["increment","decrement","allocate","deallocate"],"example":"allocate","x-go-type":"model.TransactionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"}},"product_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"quantity":{"description":"The amount of stock affected by the stock transaction.","type":"integer","format":"int64","example":5},"location":{"description":"The slug of the location that the transaction should act on.","type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"}},"title":"TransactionResponseAttributes"},"meta":{"type":"object","required":["timestamps"],"properties":{"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"TransactionResponse"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Transactions(Inventory_mli)

Methods to allow you to modify and view a products stock via transactions.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Update a Location

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Location"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/inventories/locations/{location_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates an Inventory Location

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"location_uuid","in":"path","description":"The unique identifier of the location.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["inventory_location"],"example":"inventory_location","title":"InventoryLocationType"},"attributes":{"properties":{"name":{"type":"string","minLength":3,"maxLength":1024,"example":"Milton Keynes Warehouse"},"external_ref":{"type":"string","minLength":3,"maxLength":1024,"example":"mk-stock-warehouse-walnut-tree","nullable":true},"slug":{"type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"},"description":{"type":"string","minLength":3,"maxLength":1024,"example":"Southern dispatch location for all inventory","nullable":true},"address":{"type":"array","minItems":1,"maxItems":8,"nullable":true,"items":{"type":"string","maxLength":1024,"nullable":true}},"geolocation":{"type":"object","nullable":true,"description":"The longitude and latitude of a location.","required":["lat","lon"],"properties":{"lat":{"type":"number","format":"double","nullable":false,"example":51.477928},"lon":{"type":"number","format":"double","nullable":false,"example":-0.001545}},"example":{"lat":51.477928,"lon":-0.001545},"title":"GeolocationDetails"}},"title":"LocationUpdateAttributes"}},"title":"LocationUpdateRequest"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The location was updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["inventory_location"],"example":"inventory_location","title":"InventoryLocationType"},"attributes":{"required":["name","slug"],"properties":{"name":{"type":"string","minLength":3,"maxLength":1024,"example":"Milton Keynes Warehouse"},"external_ref":{"type":"string","minLength":3,"maxLength":1024,"example":"mk-stock-warehouse-walnut-tree"},"slug":{"type":"string","minLength":1,"maxLength":128,"example":"milton-keynes-warehouse"},"description":{"type":"string","minLength":3,"maxLength":1024,"example":"Southern dispatch location for all inventory"},"address":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","maxLength":1024}},"geolocation":{"type":"object","nullable":true,"description":"The longitude and latitude of a location.","required":["lat","lon"],"properties":{"lat":{"type":"number","format":"double","nullable":false,"example":51.477928},"lon":{"type":"number","format":"double","nullable":false,"example":-0.001545}},"example":{"lat":51.477928,"lon":-0.001545},"title":"GeolocationDetails"}},"title":"LocationAttributes"},"meta":{"type":"object","required":["timestamps"],"properties":{"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"Meta"}},"title":"Location"}}},"example":{"data":{"id":"ebc7652d-bb7d-4359-9a83-78f2998208d9","type":"inventory_location","attributes":{"name":"Milton Keynes Warehouse","external_ref":"mk-stock-warehouse-walnut-tree","slug":"milton-keynes-warehouse","description":"Southern dispatch location for all inventory","address":["Troughton Supplies","38 Pipernel Grove","Walnut Tree","MK7 4UL"],"geolocation":{"lat":-90,"lon":180}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update Stock for Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Stock for Product"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/inventories/{product_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates the inventory for the specified product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"product_uuid","in":"path","description":"The unique identifier of the product.","required":true,"schema":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock","title":"StockType"},"attributes":{"properties":{"locations":{"type":"object","additionalProperties":{"type":"object","required":["available"],"properties":{"available":{"type":"integer","format":"int64","example":20}},"nullable":true,"title":"NullableLocation"},"title":"NullableLocations"}},"title":"StockUpdateAttributes"}},"title":"StockUpdateRequest"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The stock item was updated successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"type":{"type":"string","enum":["stock"],"default":"stock","example":"stock","title":"StockType"},"attributes":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30},"locations":{"type":"object","additionalProperties":{"type":"object","required":["available","total","allocated"],"properties":{"available":{"type":"integer","format":"int64","example":20},"allocated":{"type":"integer","format":"int64","example":10},"total":{"type":"integer","format":"int64","example":30}}},"title":"StockLocations"}},"title":"StockResponseAttributes"},"meta":{"type":"object","required":["stock_id","timestamps"],"properties":{"stock_id":{"type":"string","description":"The unique identifier.","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000000","title":"UUID"},"timestamps":{"required":["created_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"StockMeta"}},"title":"StockResponse"}},"required":["data"]}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"Your request was invalid"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No location found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":500},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Modifier

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Modifier"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/pricebooks/{pricebookID}/modifiers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price. This enables you to configure the price of child products, for example, to be lower than its base product, without having to individually update the price of your child products. There are three types of price modifier.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"Unique identifier of a Price Book","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"PriceModifierCreateData","description":"Json-api style data object containing a price modifier to be created.","properties":{"data":{"type":"object","title":"PriceModifier","properties":{"type":{"type":"string","x-go-name":"Type","default":"price-modifier","example":"price-modifier","enum":["price-modifier"]},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"name":{"description":"A name for the modifier. You must give the price modifier a unique name. Price modifier names are case-sensitive.","type":"string","example":"large-supplement","minLength":1,"x-go-name":"Name"},"modifier_type":{"description":"There are three modifier types.\n   * `price_increment` - Increases the price of a product.\n   * `price_decrement` - Decreases the price of a product.\n   * `price_equals` - Sets the price of a product to the amount you specify.\n","type":"string","example":"price_equals","enum":["price_equals","price_increment","price_decrement"],"x-go-name":"ModifierType"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true}},"required":["name","modifier_type","currencies"],"additionalProperties":false}},"required":["type","attributes"],"additionalProperties":false,"x-go-name":"PriceModifierCreate"}},"required":["data"],"additionalProperties":false,"x-go-name":"PriceModifierCreateData"}}},"description":"The price modifier to create within a price book.","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The created price modifier","content":{"application/json":{"schema":{"type":"object","title":"PriceModifierData","description":"Json-api style data object containing a single price modifier.","properties":{"data":{"type":"object","title":"PriceModifier","description":"A price modifier with the following attributes.","properties":{"type":{"type":"string","example":"price-modifier","default":"price-modifier","enum":["price-modifier"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique identifier associated with the price modifier. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"name":{"description":"A name for the modifier. You must give the price modifier a unique name. Price modifier names are case-sensitive.","type":"string","example":"large-supplement"},"modifier_type":{"description":"There are three modifier types.\n   * `price_increment` - Increases the price of a product.\n   * `price_decrement` - Decreases the price of a product.\n   * `price_equals` - Sets the price of a product to the amount you specify.\n","type":"string","example":"price_equals","enum":["price_equals","price_increment","price_decrement"]},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","modifier_type","currencies"]},"id":{"description":"A unique identifier for the price modifier.","type":"string","example":"37f2eed6-0bea-4d0b-a3c6-24cc76143bfd","x-go-name":"ID"},"meta":{"type":"object","properties":{"owner":{"description":"The product owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"PriceModifier"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/modifiers/f5bd1fc7-48a2-40ac-88dd-2bd9985050cd","nullable":true}},"title":"links-modifier"}},"required":["data"],"additionalProperties":false,"x-go-name":"PriceModifierData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The modifier already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Create a Price Book

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Price Book"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/pricebooks"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a price book. You can add the prices to the price book now or update the price book later.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"PricebookCreateData","properties":{"data":{"type":"object","title":"PricebookWithoutId","properties":{"type":{"type":"string","x-go-name":"Type","default":"pricebook","example":"pricebook","enum":["pricebook"]},"attributes":{"type":"object","properties":{"description":{"description":"A brief description that describes the purpose of a price book, for example, flash sale pricing or preferred customer pricing.","type":"string","example":"This is a price book","x-go-name":"Description","nullable":true},"name":{"description":"The name of the price book. Price books must have a unique name.","type":"string","example":"pricebook-store-abc","minLength":1,"x-go-name":"Name"},"external_ref":{"description":"A unique attribute that you can use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true}},"required":["name"],"additionalProperties":false}},"required":["type","attributes"],"additionalProperties":false,"x-go-name":"PricebookCreateParam"}},"required":["data"],"additionalProperties":false,"x-go-name":"PricebookCreateData","example":{"data":{"attributes":{"external_ref":"an-external-ref","description":"This is a test price book","name":"Standard Price Book"},"type":"pricebook"}}}}},"description":"Creates a price book with the following attributes.","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"A price book with the following attributes.","content":{"application/json":{"schema":{"type":"object","title":"PricebookData","description":"A price book with the following attributes.","properties":{"data":{"type":"object","title":"Pricebook","description":"A price book with the following attributes.","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"ID"},"type":{"description":"Always `pricebook`.","type":"string","x-go-name":"Type","default":"pricebook","example":"pricebook","enum":["pricebook"]},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"an-external-ref","x-go-name":"External Ref","nullable":true},"description":{"description":"A brief description that outlines the purpose of a price book, for example, flash sale pricing or preferred customer pricing.","type":"string","example":"This is a test price book","x-go-name":"Description","nullable":true},"name":{"description":"The name of a price book. Price books must have a unique name","type":"string","example":"Standard Price Book","x-go-name":"Name","nullable":true},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","created_at","updated_at"]},"meta":{"type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["id","type","attributes"],"additionalProperties":false,"x-go-name":"Pricebook"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7","nullable":true}},"title":"links-pricebook"}},"required":["data"],"additionalProperties":false,"x-go-name":"PricebookData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price book already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Add a Product Price to a Price Book

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Add a Product Price to a Price Book"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/pricebooks/{pricebookID}/prices"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Price books contain prices for the products in your catalog. Use the Prices API to adds the prices for a product to a specified price book. If the prices for the product already exist in the price book, the operation fails and the existing product prices are not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"ProductPriceCreateData","description":"A product price with the following attributes.","properties":{"data":{"type":"object","title":"ProductPriceCreateArg","properties":{"type":{"type":"string","example":"product-price","default":"product-price","enum":["product-price"]},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"sku":{"description":"The product SKU that the prices belongs to.","type":"string","minLength":1,"example":"product-sku-a"},"sales":{"type":"object","description":"The sales price that an item is eligible for based on the price book.","example":{"summer":{"schedule":{"valid_form":"2023-12-24T09:00:00","valid_to":"2023-12-25T09:00:00"},"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"additionalProperties":{"type":"object","description":"The name of the sale, such as `Summer Sale`.","properties":{"bundle_ids":{"type":"array","description":"A list of product IDs in a bundle that you want to specify a sale price for.","items":{"type":"string","format":"uuid"},"x-omitempty":true,"x-go-name":"BundleIDs"},"schedule":{"type":"object","description":"The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n","properties":{"valid_from":{"description":"The start date of the sale.","type":"string","example":"2023-09-22T09:00:00Z","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"The end date of the sale.","type":"string","example":"2023-09-24T09:00:00Z","format":"date-time","x-go-name":"ValidTo","nullable":true},"rrule":{"type":"string","description":"Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n","example":"FREQ=WEEKLY;BYDAY=SA,SU","x-go-name":"RecurrenceRule","nullable":true},"tzid":{"type":"string","description":"Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n","example":"Europe/London","x-go-name":"Timezone","nullable":true}},"x-go-name":"Schedule","nullable":true,"title":"schedule"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"}},"title":"sale"},"title":"sales"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-external-ref","x-go-name":"External Ref","nullable":true},"admin_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"admin-attributes"},"shopper_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"shopper-attributes"}},"required":["currencies","sku"]}},"required":["type","attributes"],"additionalProperties":false,"x-go-name":"ProductPriceCreateArg"}},"required":["data"],"additionalProperties":false,"x-go-name":"ProductPriceCreateData"}}},"description":"A product price with the following attributes.","required":true,"x-examples":{"application/json":{"regular-price":{"summary":"Create a Regular Price","value":{"data":{"type":"product-price","attributes":{"sku":"product-r1","currencies":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":73,"includes_tax":true},"CAD":{"amount":127,"includes_tax":false}}}}}},"volume-price":{"summary":"Create a Volume Price","value":{"data":{"type":"product-price","attributes":{"sku":"product-v1","currencies":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}}}}}}},"sale-price":{"summary":"Create Bundle Sale Price","description":"You can assign a sale price to an option in a bundle.\n\n1. In the product price book, create a sale.\n2. Specify the bundle ID that contains the option you want to provide a sale price for.\n3. Provide the sale price for the option. You can add the same sale price for the same option using an array of bundle_ids if you want to sell the product as part of different bundles.","value":{"data":{"type":"product-price","attributes":{"sku":"product-b1","currencies":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":73,"includes_tax":true},"CAD":{"amount":127,"includes_tax":false}},"sales":{"summer":{"bundle_ids":["a3cacaa9-b5bb-4096-bb6b-af41394ca850"],"schedule":{"valid_from":"2023-12-01T12:00:00Z","valid_to":"2023-12-02T12:00:00Z"},"currencies":{"USD":{"amount":90,"includes_tax":false},"CAD":{"amount":117,"includes_tax":false},"GBP":{"amount":65,"includes_tax":true}}}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"A product price with the following attributes.","x-examples":{"application/json":{"volume-price":{"summary":"Create a Volume Price","value":{"data":{"id":"ad042b07-e86d-476a-82d5-43dda1f80d03","attributes":{"currencies":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"sales":{"summer":{"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"sku":"product-1"},"meta":{"owner":"store"},"type":"product-price"},"links":{"self":"/pcm/pricebooks/2cf0d38c-58aa-420d-8658-4385dccea609/prices/ad042b07-e86d-476a-82d5-43dda1f80d03"}}},"sale-price":{"summary":"Create Bundle Sale Price","value":{"data":{"id":"76c78677-a22a-4104-8fb7-11f1cfc3b146","attributes":{"sku":"product-1","currencies":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"sales":{"summer":{"bundle_ids":["a3cacaa9-b5bb-4096-bb6b-af41394ca850"],"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}}},"type":"product-price"},"links":{"self":"/pcm/pricebooks/2cf0d38c-58aa-420d-8658-4385dccea609/prices/76c78677-a22a-4104-8fb7-11f1cfc3b146"}}}}},"content":{"application/json":{"schema":{"type":"object","title":"ProductPriceData","description":"A product price with the following attributes.","properties":{"data":{"type":"object","title":"ProductPrice","properties":{"type":{"type":"string","example":"product-price","default":"product-price","enum":["product-price"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"sku":{"description":"The product SKU that the price belongs to.","type":"string","minLength":1,"example":"product-sku-a"},"sales":{"type":"object","description":"The sales price that an item is eligible for based on the price book.","example":{"summer":{"schedule":{"valid_form":"2023-12-24T09:00:00","valid_to":"2023-12-25T09:00:00"},"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"additionalProperties":{"type":"object","description":"The name of the sale, such as `Summer Sale`.","properties":{"bundle_ids":{"type":"array","description":"A list of product IDs in a bundle that you want to specify a sale price for.","items":{"type":"string","format":"uuid"},"x-omitempty":true,"x-go-name":"BundleIDs"},"schedule":{"type":"object","description":"The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n","properties":{"valid_from":{"description":"The start date of the sale.","type":"string","example":"2023-09-22T09:00:00Z","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"The end date of the sale.","type":"string","example":"2023-09-24T09:00:00Z","format":"date-time","x-go-name":"ValidTo","nullable":true},"rrule":{"type":"string","description":"Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n","example":"FREQ=WEEKLY;BYDAY=SA,SU","x-go-name":"RecurrenceRule","nullable":true},"tzid":{"type":"string","description":"Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n","example":"Europe/London","x-go-name":"Timezone","nullable":true}},"x-go-name":"Schedule","nullable":true,"title":"schedule"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"}},"title":"sale"},"title":"sales"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"created_at":{"description":"The date and time when the price was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"},"admin_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"admin-attributes"},"shopper_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"shopper-attributes"}},"required":["sku"]},"id":{"description":"The unique identifier for the product price.","type":"string","example":"a915553d-935d-4d56-870b-817b47a44a99","x-go-name":"ID"},"meta":{"description":"Information that provides context to other data sets.","type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true},"pricebook_id":{"description":"The unique identifier of the price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"Pricebook ID"}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"ProductPrice"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/prices/ad042b07-e86d-476a-82d5-43dda1f80d03","nullable":true}},"title":"links-price"}},"required":["data"],"additionalProperties":false,"x-go-name":"ProductPriceData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style Error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Delete a Modifier

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Modifier"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/pricebooks/{pricebookID}/modifiers/{modifierID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the specified price book modifier.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"Unique identifier of a Price Book","required":true,"schema":{"type":"string"}},{"name":"modifierID","in":"path","description":"Unique identifier of a Price Book Modifier","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"A 204 response indicates that the price modifiers have been deleted"},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The modifier already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Delete a Price Book by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Price Book by ID"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/pricebooks/{pricebookID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the specified price book and all prices in the price book. It does not delete the products. In addition, pricing details in the orders referring to the deleted price book are not deleted.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"A 204 response indicates that the price book has been deleted."},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price book already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Delete a Product Price from a Price Book

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Product Price from a Price Book"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/pricebooks/{pricebookID}/prices/{priceID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a product price from the specified price book.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}},{"name":"priceID","in":"path","description":"A unique identifier of a price book price.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"A 204 response indicates that the product prices have been deleted"},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style Error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Modifier

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Modifier"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/pricebooks/{pricebookID}/modifiers/{modifierID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the specified price book modifier from the specified price book.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"Unique identifier of a Price Book","required":true,"schema":{"type":"string"}},{"name":"modifierID","in":"path","description":"Unique identifier of a Price Book Modifier","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The price modifier.","content":{"application/json":{"schema":{"type":"object","title":"PriceModifierData","description":"Json-api style data object containing a single price modifier.","properties":{"data":{"type":"object","title":"PriceModifier","description":"A price modifier with the following attributes.","properties":{"type":{"type":"string","example":"price-modifier","default":"price-modifier","enum":["price-modifier"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique identifier associated with the price modifier. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"name":{"description":"A name for the modifier. You must give the price modifier a unique name. Price modifier names are case-sensitive.","type":"string","example":"large-supplement"},"modifier_type":{"description":"There are three modifier types.\n   * `price_increment` - Increases the price of a product.\n   * `price_decrement` - Decreases the price of a product.\n   * `price_equals` - Sets the price of a product to the amount you specify.\n","type":"string","example":"price_equals","enum":["price_equals","price_increment","price_decrement"]},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","modifier_type","currencies"]},"id":{"description":"A unique identifier for the price modifier.","type":"string","example":"37f2eed6-0bea-4d0b-a3c6-24cc76143bfd","x-go-name":"ID"},"meta":{"type":"object","properties":{"owner":{"description":"The product owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"PriceModifier"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/modifiers/f5bd1fc7-48a2-40ac-88dd-2bd9985050cd","nullable":true}},"title":"links-modifier"}},"required":["data"],"additionalProperties":false,"x-go-name":"PriceModifierData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The modifier already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Gets a list of all modifiers

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Gets a list of all modifiers"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/pricebooks/{pricebookID}/modifiers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of price modifiers for the specified price book.

### Filtering

Filtering is supported on this endpoint. For the general syntax, see [Filtering](/guides/Getting-Started/filtering).

You can filter on the following attributes and operators.

| Operator | Attribute | Description | Example |
| --- | --- | --- | --- |
| `eq` | `external_ref`, `name` | Checks if the values you provide matches a price modifier. | `filter=eq(name,largesupplement)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","description":"This endpoint supports filtering. See [Filtering]().\n","name":"filter","required":false,"schema":{"type":"string"}},{"name":"page[limit]","in":"query","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"name":"page[offset]","in":"query","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page offset is set, the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}},{"name":"pricebookID","in":"path","description":"Unique identifier of a Price Book","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The price modifier list.","content":{"application/json":{"schema":{"type":"object","title":"PriceModifierListData","description":"Json-api style array containing a list of price modifiers.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":1,"nullable":true}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","example":10,"x-omitempty":false},"offset":{"description":"The current offset by number of pages.","type":"integer","example":0,"x-omitempty":false},"current":{"description":"The current number of pages.","type":"integer","example":0,"x-omitempty":false},"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1,"x-omitempty":false}}}}},"data":{"type":"array","items":{"type":"object","title":"PriceModifier","description":"A price modifier with the following attributes.","properties":{"type":{"type":"string","example":"price-modifier","default":"price-modifier","enum":["price-modifier"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique identifier associated with the price modifier. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"name":{"description":"A name for the modifier. You must give the price modifier a unique name. Price modifier names are case-sensitive.","type":"string","example":"large-supplement"},"modifier_type":{"description":"There are three modifier types.\n   * `price_increment` - Increases the price of a product.\n   * `price_decrement` - Decreases the price of a product.\n   * `price_equals` - Sets the price of a product to the amount you specify.\n","type":"string","example":"price_equals","enum":["price_equals","price_increment","price_decrement"]},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","modifier_type","currencies"]},"id":{"description":"A unique identifier for the price modifier.","type":"string","example":"37f2eed6-0bea-4d0b-a3c6-24cc76143bfd","x-go-name":"ID"},"meta":{"type":"object","properties":{"owner":{"description":"The product owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"PriceModifier"}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/modifiers","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/modifiers?page[offset]=0&page[limit]=25","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/modifiers?page[offset]=0&page[limit]=25","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/modifiers?page[offset]=0&page[limit]=25","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/modifiers?page[offset]=25&page[limit]=25","nullable":true}},"title":"links-modifiers"}},"required":["data"],"additionalProperties":false,"x-go-name":"PriceModifierListData"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The modifier already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Price Book by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Price Book by ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/pricebooks/{pricebookID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the specified price book. To include prices in the response, append `?include=prices` to the path.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"include","in":"query","description":"To include product prices in a response, add `include=prices`.","required":false,"allowEmptyValue":true,"schema":{"type":"string","enum":["prices"]}},{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The price book.","content":{"application/json":{"schema":{"type":"object","title":"PricebookWithPricesData","description":"Json-api style data object containing a price book and its prices.","properties":{"data":{"type":"object","title":"Pricebook","description":"A price book with the following attributes.","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"ID"},"type":{"description":"Always `pricebook`.","type":"string","x-go-name":"Type","default":"pricebook","example":"pricebook","enum":["pricebook"]},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"an-external-ref","x-go-name":"External Ref","nullable":true},"description":{"description":"A brief description that outlines the purpose of a price book, for example, flash sale pricing or preferred customer pricing.","type":"string","example":"This is a test price book","x-go-name":"Description","nullable":true},"name":{"description":"The name of a price book. Price books must have a unique name","type":"string","example":"Standard Price Book","x-go-name":"Name","nullable":true},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","created_at","updated_at"]},"meta":{"type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["id","type","attributes"],"additionalProperties":false,"x-go-name":"Pricebook"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7","nullable":true}},"title":"links-pricebook"},"included":{"type":"array","items":{"type":"object","title":"ProductPrice","properties":{"type":{"type":"string","example":"product-price","default":"product-price","enum":["product-price"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"sku":{"description":"The product SKU that the price belongs to.","type":"string","minLength":1,"example":"product-sku-a"},"sales":{"type":"object","description":"The sales price that an item is eligible for based on the price book.","example":{"summer":{"schedule":{"valid_form":"2023-12-24T09:00:00","valid_to":"2023-12-25T09:00:00"},"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"additionalProperties":{"type":"object","description":"The name of the sale, such as `Summer Sale`.","properties":{"bundle_ids":{"type":"array","description":"A list of product IDs in a bundle that you want to specify a sale price for.","items":{"type":"string","format":"uuid"},"x-omitempty":true,"x-go-name":"BundleIDs"},"schedule":{"type":"object","description":"The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n","properties":{"valid_from":{"description":"The start date of the sale.","type":"string","example":"2023-09-22T09:00:00Z","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"The end date of the sale.","type":"string","example":"2023-09-24T09:00:00Z","format":"date-time","x-go-name":"ValidTo","nullable":true},"rrule":{"type":"string","description":"Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n","example":"FREQ=WEEKLY;BYDAY=SA,SU","x-go-name":"RecurrenceRule","nullable":true},"tzid":{"type":"string","description":"Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n","example":"Europe/London","x-go-name":"Timezone","nullable":true}},"x-go-name":"Schedule","nullable":true,"title":"schedule"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"}},"title":"sale"},"title":"sales"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"created_at":{"description":"The date and time when the price was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"},"admin_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"admin-attributes"},"shopper_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"shopper-attributes"}},"required":["sku"]},"id":{"description":"The unique identifier for the product price.","type":"string","example":"a915553d-935d-4d56-870b-817b47a44a99","x-go-name":"ID"},"meta":{"description":"Information that provides context to other data sets.","type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true},"pricebook_id":{"description":"The unique identifier of the price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"Pricebook ID"}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"ProductPrice"},"nullable":true}},"required":["data"],"additionalProperties":false}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price book already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get all Price Books

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Price Books"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/pricebooks"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all price books.

### Filtering

Filtering is supported on this endpoint. For the general syntax, see [Filtering](/guides/Getting-Started/filtering).

 You can filter on the following attributes and operators.

 | Operator | Attribute | Description | Example |
 | --- | --- | --- | --- |
 | `eq` | `external_ref` | Equals. Checks if the values you provide matches a price book. | `filter=eq(external_ref,some-external-ref)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","description":"You can filter on this endpoint. See [Filtering](#filtering).\n","name":"filter","required":false,"schema":{"type":"string"}},{"name":"page[limit]","in":"query","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"name":"page[offset]","in":"query","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page offset is set, the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of price books.","content":{"application/json":{"schema":{"type":"object","title":"PricebookListData","description":"Json-api style array containing a list of price books","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":1,"nullable":true}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","example":10,"x-omitempty":false},"offset":{"description":"The current offset by number of pages.","type":"integer","example":0,"x-omitempty":false},"current":{"description":"The current number of pages.","type":"integer","example":0,"x-omitempty":false},"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1,"x-omitempty":false}}}}},"data":{"type":"array","items":{"type":"object","title":"Pricebook","description":"A price book with the following attributes.","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"ID"},"type":{"description":"Always `pricebook`.","type":"string","x-go-name":"Type","default":"pricebook","example":"pricebook","enum":["pricebook"]},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"an-external-ref","x-go-name":"External Ref","nullable":true},"description":{"description":"A brief description that outlines the purpose of a price book, for example, flash sale pricing or preferred customer pricing.","type":"string","example":"This is a test price book","x-go-name":"Description","nullable":true},"name":{"description":"The name of a price book. Price books must have a unique name","type":"string","example":"Standard Price Book","x-go-name":"Name","nullable":true},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","created_at","updated_at"]},"meta":{"type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["id","type","attributes"],"additionalProperties":false,"x-go-name":"Pricebook"}},"links":{"description":"Links are used to allow you to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)&page[offset]=0&page[limit]=25","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)&page[offset]=0&page[limit]=25","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)&page[offset]=0&page[limit]=25","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7?filter=like(name,*Standard*)&page[offset]=25&page[limit]=25","nullable":true}},"title":"links-pricebooks"}},"required":["data"],"additionalProperties":false,"x-go-name":"PricebookListData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price book already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Gets all Prices

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Gets all Prices"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/pricebooks/prices"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Allows you to retrieve all prices for a product, irrespective of the different price books that include that product's price. For example, you can filter for all prices for a specified `sku`, or filter for all prices changed before or after a given date. This will retrieve prices from all price books.

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).

| Operator | Attribute | Description | Example |
| --- | --- | --- | --- |
| `eq` | `external_ref`, `sku`, `id` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | `filter=eq(sku,some-sku)` |
| `in` | `external_ref`, `sku`, `id` | In. Checks if the values are included in the specified list. If they are, the condition is true. | `filter=in(sku,some-sku)` |
| `like` | `external_ref`, `sku` | Like. Checks if the operand contains the specified string. Wildcards are supported. | `filter=like(sku,some-sku)` |
| `gt` | `updated_at`, `created_at` | Greater than. Checks if the value on the left of the operator is greater than the value on the right. If it is, the condition is true. | `filter=gt(updated_at,2018-04-16T10:11:59.715Z)` |
| `lt` | `updated_at`, `created_at` | Less than. Checks if the value on the left of the operator is less than the value on the right. If it is, the condition is true. | `filter=lt(updated_at,2018-04-16T10:11:59.715Z)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","description":"This endpoint supports filtering. See [Filtering]().\n","name":"filter","required":false,"schema":{"type":"string"}},{"name":"page[limit]","in":"query","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"name":"page[offset]","in":"query","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page offset is set, the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The price list.","content":{"application/json":{"schema":{"type":"object","title":"PriceListData","description":"Json-api style array containing a list of prices.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","example":10,"x-omitempty":false},"offset":{"description":"The current offset by number of pages.","type":"integer","example":0,"x-omitempty":false},"current":{"description":"The current number of pages.","type":"integer","example":0,"x-omitempty":false},"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1,"x-omitempty":false}}}}},"data":{"type":"array","items":{"type":"object","title":"ProductPrice","properties":{"type":{"type":"string","example":"product-price","default":"product-price","enum":["product-price"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"sku":{"description":"The product SKU that the price belongs to.","type":"string","minLength":1,"example":"product-sku-a"},"sales":{"type":"object","description":"The sales price that an item is eligible for based on the price book.","example":{"summer":{"schedule":{"valid_form":"2023-12-24T09:00:00","valid_to":"2023-12-25T09:00:00"},"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"additionalProperties":{"type":"object","description":"The name of the sale, such as `Summer Sale`.","properties":{"bundle_ids":{"type":"array","description":"A list of product IDs in a bundle that you want to specify a sale price for.","items":{"type":"string","format":"uuid"},"x-omitempty":true,"x-go-name":"BundleIDs"},"schedule":{"type":"object","description":"The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n","properties":{"valid_from":{"description":"The start date of the sale.","type":"string","example":"2023-09-22T09:00:00Z","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"The end date of the sale.","type":"string","example":"2023-09-24T09:00:00Z","format":"date-time","x-go-name":"ValidTo","nullable":true},"rrule":{"type":"string","description":"Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n","example":"FREQ=WEEKLY;BYDAY=SA,SU","x-go-name":"RecurrenceRule","nullable":true},"tzid":{"type":"string","description":"Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n","example":"Europe/London","x-go-name":"Timezone","nullable":true}},"x-go-name":"Schedule","nullable":true,"title":"schedule"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"}},"title":"sale"},"title":"sales"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"created_at":{"description":"The date and time when the price was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"},"admin_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"admin-attributes"},"shopper_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"shopper-attributes"}},"required":["sku"]},"id":{"description":"The unique identifier for the product price.","type":"string","example":"a915553d-935d-4d56-870b-817b47a44a99","x-go-name":"ID"},"meta":{"description":"Information that provides context to other data sets.","type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true},"pricebook_id":{"description":"The unique identifier of the price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"Pricebook ID"}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"ProductPrice"}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/prices?filter=like(sku,product)","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links-prices-new"}},"required":["data"],"additionalProperties":false,"x-go-name":"PriceListData"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style Error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Get a Product Price by Price Book ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Product Price by Price Book ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/pricebooks/{pricebookID}/prices/{priceID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a specified product price (`priceId`) in the specified price book (`id`).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}},{"name":"priceID","in":"path","description":"A unique identifier of a price book price.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The product price.","content":{"application/json":{"schema":{"type":"object","title":"ProductPriceData","description":"A product price with the following attributes.","properties":{"data":{"type":"object","title":"ProductPrice","properties":{"type":{"type":"string","example":"product-price","default":"product-price","enum":["product-price"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"sku":{"description":"The product SKU that the price belongs to.","type":"string","minLength":1,"example":"product-sku-a"},"sales":{"type":"object","description":"The sales price that an item is eligible for based on the price book.","example":{"summer":{"schedule":{"valid_form":"2023-12-24T09:00:00","valid_to":"2023-12-25T09:00:00"},"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"additionalProperties":{"type":"object","description":"The name of the sale, such as `Summer Sale`.","properties":{"bundle_ids":{"type":"array","description":"A list of product IDs in a bundle that you want to specify a sale price for.","items":{"type":"string","format":"uuid"},"x-omitempty":true,"x-go-name":"BundleIDs"},"schedule":{"type":"object","description":"The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n","properties":{"valid_from":{"description":"The start date of the sale.","type":"string","example":"2023-09-22T09:00:00Z","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"The end date of the sale.","type":"string","example":"2023-09-24T09:00:00Z","format":"date-time","x-go-name":"ValidTo","nullable":true},"rrule":{"type":"string","description":"Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n","example":"FREQ=WEEKLY;BYDAY=SA,SU","x-go-name":"RecurrenceRule","nullable":true},"tzid":{"type":"string","description":"Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n","example":"Europe/London","x-go-name":"Timezone","nullable":true}},"x-go-name":"Schedule","nullable":true,"title":"schedule"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"}},"title":"sale"},"title":"sales"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"created_at":{"description":"The date and time when the price was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"},"admin_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"admin-attributes"},"shopper_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"shopper-attributes"}},"required":["sku"]},"id":{"description":"The unique identifier for the product price.","type":"string","example":"a915553d-935d-4d56-870b-817b47a44a99","x-go-name":"ID"},"meta":{"description":"Information that provides context to other data sets.","type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true},"pricebook_id":{"description":"The unique identifier of the price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"Pricebook ID"}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"ProductPrice"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/prices/ad042b07-e86d-476a-82d5-43dda1f80d03","nullable":true}},"title":"links-price"}},"required":["data"],"additionalProperties":false,"x-go-name":"ProductPriceData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style Error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Gets all Prices by Price Book ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Gets all Prices by Price Book ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/pricebooks/{pricebookID}/prices"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all the product prices in the specified price book.

### Filtering

This endpoint supports filtering. For general syntax, see [Filtering](/guides/Getting-Started/filtering).

| Operator | Attribute | Description | Example |
| --- | --- | --- | --- |
| `eq` | `external_ref`, `sku` | Checks if the values you provide matches a price. | `filter=eq(sku,some-sku)` |
| `in` | `sku` | Checks if the values you provide are included in a product SKU. | `filter=in(sku,some-sku)' |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","description":"This endpoint supports filtering. See [Filtering]().\n","name":"filter","required":false,"schema":{"type":"string"}},{"name":"page[limit]","in":"query","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","required":false,"schema":{"type":"integer","format":"int64","minimum":1}},{"name":"page[offset]","in":"query","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page offset is set, the [**page length**](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000}},{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The product price list.","content":{"application/json":{"schema":{"type":"object","title":"ProductPriceListData","description":"Json-api style array containing a list of product prices.","properties":{"meta":{"type":"object","description":"Contains the results for the entire collection.","title":"PageMeta","properties":{"results":{"type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":1,"nullable":true}}},"page":{"type":"object","properties":{"limit":{"description":"The maximum number of records for all pages.","type":"integer","example":10,"x-omitempty":false},"offset":{"description":"The current offset by number of pages.","type":"integer","example":0,"x-omitempty":false},"current":{"description":"The current number of pages.","type":"integer","example":0,"x-omitempty":false},"total":{"description":"The total number of records for the entire collection.","type":"integer","example":1,"x-omitempty":false}}}}},"data":{"type":"array","items":{"type":"object","title":"ProductPrice","properties":{"type":{"type":"string","example":"product-price","default":"product-price","enum":["product-price"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"sku":{"description":"The product SKU that the price belongs to.","type":"string","minLength":1,"example":"product-sku-a"},"sales":{"type":"object","description":"The sales price that an item is eligible for based on the price book.","example":{"summer":{"schedule":{"valid_form":"2023-12-24T09:00:00","valid_to":"2023-12-25T09:00:00"},"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"additionalProperties":{"type":"object","description":"The name of the sale, such as `Summer Sale`.","properties":{"bundle_ids":{"type":"array","description":"A list of product IDs in a bundle that you want to specify a sale price for.","items":{"type":"string","format":"uuid"},"x-omitempty":true,"x-go-name":"BundleIDs"},"schedule":{"type":"object","description":"The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n","properties":{"valid_from":{"description":"The start date of the sale.","type":"string","example":"2023-09-22T09:00:00Z","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"The end date of the sale.","type":"string","example":"2023-09-24T09:00:00Z","format":"date-time","x-go-name":"ValidTo","nullable":true},"rrule":{"type":"string","description":"Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n","example":"FREQ=WEEKLY;BYDAY=SA,SU","x-go-name":"RecurrenceRule","nullable":true},"tzid":{"type":"string","description":"Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n","example":"Europe/London","x-go-name":"Timezone","nullable":true}},"x-go-name":"Schedule","nullable":true,"title":"schedule"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"}},"title":"sale"},"title":"sales"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"created_at":{"description":"The date and time when the price was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"},"admin_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"admin-attributes"},"shopper_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"shopper-attributes"}},"required":["sku"]},"id":{"description":"The unique identifier for the product price.","type":"string","example":"a915553d-935d-4d56-870b-817b47a44a99","x-go-name":"ID"},"meta":{"description":"Information that provides context to other data sets.","type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true},"pricebook_id":{"description":"The unique identifier of the price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"Pricebook ID"}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"ProductPrice"}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/prices?filter=like(sku,*product*)","nullable":true},"first":{"description":"Always the first page.","type":"string","format":"uri","nullable":true},"last":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"prev":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true},"next":{"description":"This is `null` if there is only one page.","type":"string","format":"uri","nullable":true}},"title":"links-prices"}},"required":["data"],"additionalProperties":false,"x-go-name":"ProductPriceListData"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style Error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Import a Price Book and Prices

You can create and update product price books and prices in bulk, at both organization and store level, using the Price Book Import API. This is useful, for example, if you have a promotion and want to update 50,000 product prices. Rather than having to go to each price book and manually edit 50,000 prices, you can use the Price Book Import API to bulk update all your product prices at the same time, including setting different prices for different currencies.

You can create/update:

- price books.
- prices.
  - sales pricing for products and product bundles with SKUs.
  - volume pricing (tiers).

The following are not supported by the Price Book Import API:

- price modifiers
- SKUless bundles
- Bundle sale prices

The API uses a [JSONL](https://jsonlines.org/) file. The JSONL file can be compressed to a GZIP file. Here is an [example of a JSONL file](/assets/example_file_all.jsonl).

A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time.

### Characteristics of Price Book Import

The Price Book Import API reads the entire file and then creates/updates the price book objects. This means the price book objects can be in any order in the file.

Price book imports are asynchronous. When you send a request to the price book import API, it triggers an asynchronous job to create/update the price books and product prices. You can see the status of a job using Get a job.

Jobs are processed one at a time. You can continue to send price book import requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See [Jobs](/docs/api/pxm/products/jobs).

The API works on a "best endeavours" approach. In other words, the API does its best to create/update the price book objects based on the file that you provide. You can then use the results of the job to understand what objects the API created/updated and to troubleshoot any errors. See [Price Book Import API Results](#price-book-import-api-results).

Price book imports are processed sequentially in the order that you send your import API requests.

### Price Book Import Unique Identifiers

The API uses unique identifiers to identify the objects to be created/updated.

You must provide either an `id` or an `external_ref`. You may have both, but you must have at least one.

- If you supply an `id` then the ID must exist for the object to be updated. If the ID does not exist, this causes an error.
- If you supply an `external_ref` then the API checks if the external reference exists and updates the object. If the external reference does not exist, the API creates a new object with the external reference you have specified.

#### Price Book Unique Identifiers

The following table describes the unique identifiers you must provide, depending on whether you are creating or updating a price book.

| Action | Unique Identifiers |
| --- | --- |
| Creating | Unique price book name.`external_ref` for the price book. |
| Updating | `id` and/or `external_ref` for the price book. |

#### Price Unique Identifiers

The following table describes the unique identifiers you must provide, depending on whether you are creating or updating a price.

 | Action | Unique Identifiers |
 | --- | --- |
 | Creating | The product SKU that the price belongs to.`id` and/or `external_ref` for the price book where you want to create the new price.`external_ref` for the price. The `external_ref` for a price must be unique within a price book. However, you can have duplicate price external references across multiple price books. |
 | Updating | The product SKU that the price belongs to.`pricebook_external_ref` for the price book where you want to update the new price.`id` and/or `external_ref` for the price. The `external_ref` for a price must be unique within a price book. However, you can have duplicate price external references across multiple price books. |
 
 ### Price Book Import File
 
 You can create/update price book objects using [Import a Price](/docs/api/pxm/pricebooks/import-a-price-book-and-prices).
 
 The API uses a [JSONL](https://jsonlines.org/) file. The JSONL file can be compressed to a GZIP file. Here is an [example of a JSONL file](/assets/example_file_all.jsonl).
 
 A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time.
 
 - The `pricebook` Object - The attributes you can specify for a `pricebook` object are the attributes you specify when [creating a pricebook](/docs/api/pxm/pricebooks/create-pricebook). 
 
 - The `product-price` Object - The attributes you can specify for a `product-price` object are the attributes you specify when [adding a price to a price book](/docs/api/pxm/pricebooks/create-product-price).
 
 Once your import file is created, use the [import a price book and prices API to import](/docs/api/pxm/pricebooks/import-pricebook) the file.
 
 ### Importing product prices with custom attributes
 
 There are two types of custom attributes a price can have `shopper_attributes` and `admin_attributes`. When importing product prices with custom attributes, you can import a price with:
 
 - up to 100 `admin_attributes`
 - up to 100 `shopper_attributes`
 
 Ensure that a price adheres to these limits for custom attributes.
 
 ### Price Book Import API Results
 
 The API works on a "best endeavours" approach. In other words, the API does its best to create/update the price book objects based on the file that you provide.
 
 If there are any errors, then the import is aborted and the job fails with an error. You can then use the job results to understand what objects the API created/updated until the import failed and to troubleshoot any errors. 
 
 Once you have fixed any errors, you can then use the [**import a price**](/docs/api/pxm/pricebooks/import-pricebook) endpoint to send the request again.
 
 The following table describes the import messages reported by the API.
 
 | Import Message | Description |
 | --- | --- |
 | import price book_id: '%v' belongs to Organization", price book.ID))"import price book external_ref: '%v' belongs to Organization", *price book.ExternalRef) | This group of messages tells you that these imported objects belong to an organization. 
 | matched price with pricebook_id - had different external_refmatched price with pricebook_id - belongs to different price bookmatched price with pricebook_id - price_id not foundmatched price with pricebook_id - price_id belongs to an organization.matched price with pricebook_id - duplicate external_ref detectedmatched price with pricebook_id - duplicate SKU detected - required SKU. | This group of messages is telling you that the price was updated but there is an issue with another attribute that requires fixing. |
 
 The following table describes the import errors reported by the API.
 
 | Error | Description |
 | --- | --- |
 | error processing gzip fileerror processing object '%v' invalid json provided | This group of errors indicates that there is a problem with the JSONL file. You must fix the problems with the file and try the import again. |
 | duplicate price book Id '%s' in imported price booksmissing attributes for price bookinvalid type for external_ref for price bookmissing attributes for pricemissing sku for pricemissing sku for priceinvalid type for external_ref for priceinvalid type for sku for pricemissing price book_id/price book_external_ref for priceprice book id(s) not foundprice book external ref(s) not foundprice book id not found:duplicate external ref foundprice Ids not foundprice book external refs not found | This group of errors indicates that there is some information missing from the objects you are trying to create/update. |

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Import a Price

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Import a Price"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/pricebooks/import"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can create and update product price books and prices in bulk, at both organization and store level, using the Price Book Import API. This is useful, for example, if you have a promotion and want to update 50,000 product prices. Rather than having to go to each price book and manually edit 50,000 prices, you can use the Price Book Import API to bulk update all your product prices at the same time, including setting different prices for different currencies.
 
 The API uses a [JSONL](https://jsonlines.org/) file. The JSONL file can be compressed to a GZIP file. Here is an [example of a JSONL file](/assets/example_file_all.jsonl).
 
 The API works on a "best endeavours" approach. In other words, the API does its best to create/update the price book objects based on the file that you provide. If there are any errors, then the import is aborted, and the job fails with an error. You can then use the job results to understand what objects the API created/updated until the import failed, and to troubleshoot any errors. See [Import Results](#tag/Price-Book-Import).
 
 Price book imports are processed sequentially in the order that you send your import API requests.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The created price book","content":{"application/json":{"schema":{"type":"object","title":"JobData","description":"Json-api style data object containing a job.","properties":{"data":{"type":"object","title":"Job","description":"Top level entity in the jobs domain model. It contains a job details.","properties":{"id":{"type":"string","example":"0dd4e7de-006f-460f-a43e-a581f375cedc","x-go-name":"ID"},"attributes":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"},"started_at":{"type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"StartedAt","nullable":true},"completed_at":{"type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"CompletedAt","nullable":true},"type":{"type":"string","example":"pricebook-import","x-go-name":"Type"},"status":{"type":"string","example":"pending","x-go-name":"Status"}},"required":["created_at","updated_at","type","status"]},"meta":{"type":"object","properties":{"x_request_id":{"type":"string","example":"2d70776e-c2b0-4446-84e6-d08a24edfca4","x-go-name":"XRequestID"}},"required":["x_request_id"]}},"required":["id","attributes","meta"],"additionalProperties":false,"x-go-name":"Job"}},"required":["data"],"additionalProperties":false,"x-go-name":"JobData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price book already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Price Book Modifiers

You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price. This enables you to configure the price of child products, for example, to be lower than its base product, without having to individually update the price of your child products. There are three types of price modifier.

| Modifier          | Data Type | Effect                                       |
|:------------------|:----------|:---------------------------------------------|
| `price_increment` | `string`  | Increases the price of a product.            |
| `price_decrement` | `string`  | Decreases the price of a product.            |
| `price_equals`    | `string`  | Sets the price of a product to the amount you specify. |

The following is an overview of the steps you need to follow to use price modifiers.

1. Create a price modifier. You must give the price modifier a unique name. For more information, see [Create a Price Modifier](/docs/api/pxm/pricebooks/create-price-modifier).
1. Build your child products with the new product modifier.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Price Books Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/pricebooks/pricebooks.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Price Books Introduction"}
>
</Heading>

You can use the price books service to configure your product pricing. Your price books are associated with your catalogs. Creating separate price books enables you to:

- Maintain consistent and accurate pricing across all your product listings and channels.
- Provide competitive pricing by creating different price books for different channels. For example, different pricing for different geographical regions, based on standard of living costs.
- Provide personalized pricing by creating personalized price books. For example, pricing for loyalty customers versus new customers.
- Enable cross-selling and upselling by offering sales and volume pricing for your products.
- Create price-books based on real-time adjustments such as inventory levels and market conditions.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Price Books

Price books contain prices for the products in your catalog. Each catalog must have one price book. In your storefront, the product prices are displayed in the currency for the selected locale. If a product in the catalog does not have a price in the price book, the product is displayed without a price. 

A price book can be associated with multiple catalogs.

Following on from this, you can associate more than one price book with a catalog. Price book stacking allows you to create multiple price books for different scenarios, such as seasonal sales, business versus retail customer pricing, and reward programs. If you have multiple price books, when you create a catalog, you must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. For example, you may have products that have different prices based on region. You can have a price book with the standard retail pricing and then have a second price book that has different pricing for a different region. See Create a catalog.

A price book contains a list of product SKUs and the prices you want to charge for those products. If your store supports multiple locales, a price book can contain product prices in each of the supported currencies. In addition, you can configure sales and volume (tier) pricing.

:::note

Price books work with products that are defined using the Product Experience Manager resource model. If your products are defined using an earlier Products resource model, you will need to migrate products to the `pcm/products` resource before you implement price books.

:::

You can duplicate an existing price book and create a new price book. All products and prices associated with the price book are copied to the new price book. Based on the business requirements, you can use the same data or update the data.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Prices

Price books contain prices for the products in your catalog. Use the Price Books API to create price books and add product prices to the price book.

### Volume (tiers) Pricing

Using volume (tiers) pricing allows your store to offer different pricing for minimum quantities of items that your customers purchase. When a customer adds sufficient quantity of an item and meets the minimum required quantity for different pricing, all products with that item SKU are discounted in the cart. You can define the price range for different quantities of different items as in the following example:

| Quantity | Price/Each |
|:---------|:-----------|
| 1-5      | $10.50     |
| 6-10     | $10.00     |
| 11-20    | $9.50      |
| 21-50    | $8.50      |
| 51+      | $7.90      |

### Sales Pricing

With sales pricing, a store can optionally add a sale price to a product price. For example, a store can schedule seasonal pricing on products without creating a new price book and catalog ruleset. Optionally, a store can schedule the date ranges for the sale products. 

You can set a sale price for an item within a bundle so that the product is sold at the sale price when sold as part of the bundle. For example, if you have a bundle consisting of four items, you can apply a discounted price to an item within the bundle to get a bundle sales price. 

1. For sale prices in the same price book:

    - the schedules must not be exactly the same.
    - schedules can partially overlap. If the schedule does contain overlapping sales prices, the sale price of the smallest sale period is chosen.
    - if you have just one sale price, without a schedule, this is effectively a permanent price. If you want to add more sale prices to the price book, you must configure a schedule for the sale price. 

2. Sale prices in different price books can have overlapping schedules.

Both list and sale price (or was/is prices) are available in the catalog response, enabling you to display slash pricing on your storefront, depending on your requirements.

### Creating a bundle sale price

You can assign a sale price to an option in a bundle.

1. In the product price book, create a sale.
2. Specify the bundle ID that contains the option you want to provide a sale price for.
3. Provide the sale price for the option. You can add the same sale price for the same option using an array of bundle_ids if you want to sell the product as part of different bundles.

### Understanding Volume and Sale Pricing Behavior for Products

If you have configured both sale and volume pricing for your products and product bundles, the following table describes how pricing behaves in the following scenarios.

| Scenario | Description |
| --- | --- |
| Minimum quantities for volume pricing and sale pricing | (With sale schedule) If you have specified a minimum quantity of five whose price is $0.99 and at the same time, you have configured a sale for the time of purchase, then when a shopper checks out with 5 or more items, the total is based on the volume pricing. In other words, $0.99 × 5 = $4.95. Additionally, if volume pricing exist for both the product price and the sale, the volume pricing for the sale takes precedence. If no volume pricing is set in the sale, the base sale price is applied, and the volume pricing for the product price will not be applied.(With sale schedule) If a shopper's items in the cart do not meet the minimum quantity required for volume pricing, the total is calculated based on the sales price.(Without sale schedule) If the sale is a permanent sale and volume pricing is only set for the product price, then regardless of the quantity a shopper adds to a cart, the final price is always calculated based on the base sales price. However, if volume pricing has been set for the sale, the final price will be determined by the volume tier pricing set in the sale, not the base sales price.
| Two levels of volume pricing with different prices for each volume. | If you have configured two levels of volume pricing, for example, the first minimum quantity is 5 and the second minimum quantity is 10:When the quantity in the cart is =&gt; 5, then the price for the minimum quantity of 5 is used.When the quantity in the cart is =&gt; 10 then the price for the minimum quantity of 10 is used. |

### Optimizing product prices

You can add custom attributes to a product price, allowing your storefront to dynamically use these attributes in it's pricing and display logic. This enables you to optimize your pricing data, enhancing your ability to respond to market dynamics and customer preferences. Some examples of pricing optimization strategies are:

- dynamic pricing - allows you to change the price of a product based on changes in customer demand, for example, raising prices during the high-demand holiday season or segment-focused, like special offers for new customers.
- value-based pricing - allows you to offer different pricing tiers, for example, "pro" features cost more.
- cost-plus pricing - allows you to set prices by adding a specific percentage to the production cost of a single unit.

There are two types of custom attributes:

- `admin_attributes` - `admin_attributes` are not displayed in catalogs. This means `admin-attributes` can only be viewed by administrators. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.
- `shopper_attributes` - `shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators.  For example, you can set prices based on customer segments, offering different prices for wholesale and retail customers or providing discounts to loyal customers. 

Both `admin-attributes` and `shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys for each type of attribute.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Replicate a Price Book

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Replicate a Price Book"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/pricebooks/{pricebookID}/replicate"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Using this endpoint, you can replicate an existing price book. This is useful because it enables you to quickly and easily create multiple price books with the same pricing structure. When you replicate an existing price book, you can specify a new name, description, and external reference for the replicated price book. Other attributes stay the same.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"PricebookReplicateData","description":"Json-api style data object containing a price book to be replicated.","properties":{"data":{"type":"object","title":"Pricebook","description":"Price book replicate request.","properties":{"type":{"type":"string","x-go-name":"Type","default":"pricebook","example":"pricebook","enum":["pricebook"]},"attributes":{"type":"object","properties":{"description":{"type":"string","description":"A brief description outlining the purpose of a price book, such as flash sale pricing or preferred customer pricing.","example":"This is a test price book","x-go-name":"Description","nullable":true},"name":{"type":"string","description":"The name of the price book. Price books must have a unique name.","example":"pricebook-store-abc","minLength":1,"x-go-name":"Name","nullable":true},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true}},"additionalProperties":false}},"required":["type","attributes"],"additionalProperties":false,"x-go-name":"PricebookReplicate"}},"required":["data"],"additionalProperties":false,"x-go-name":"PricebookReplicateData"}}},"description":"A replicated price book with the following attributes."}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"A replicated price book with the following attributes.","content":{"application/json":{"schema":{"type":"object","title":"PricebookData","description":"A price book with the following attributes.","properties":{"data":{"type":"object","title":"Pricebook","description":"A price book with the following attributes.","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"ID"},"type":{"description":"Always `pricebook`.","type":"string","x-go-name":"Type","default":"pricebook","example":"pricebook","enum":["pricebook"]},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"an-external-ref","x-go-name":"External Ref","nullable":true},"description":{"description":"A brief description that outlines the purpose of a price book, for example, flash sale pricing or preferred customer pricing.","type":"string","example":"This is a test price book","x-go-name":"Description","nullable":true},"name":{"description":"The name of a price book. Price books must have a unique name","type":"string","example":"Standard Price Book","x-go-name":"Name","nullable":true},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","created_at","updated_at"]},"meta":{"type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["id","type","attributes"],"additionalProperties":false,"x-go-name":"Pricebook"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7","nullable":true}},"title":"links-pricebook"}},"required":["data"],"additionalProperties":false,"x-go-name":"PricebookData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price book already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Update a Modifier

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Modifier"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/pricebooks/{pricebookID}/modifiers/{modifierID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the price modifier is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"Unique identifier of a Price Book","required":true,"schema":{"type":"string"}},{"name":"modifierID","in":"path","description":"Unique identifier of a Price Book Modifier","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"PriceModifierUpdateData","description":"Json-api style data object containing a price modifier to be updated.","properties":{"data":{"type":"object","title":"PriceModifier","description":"Price modifier update request.","properties":{"id":{"description":"A unique identifier for the price modifier.","type":"string","example":"37f2eed6-0bea-4d0b-a3c6-24cc76143bfd","x-go-name":"ID"},"type":{"type":"string","x-go-name":"Type","default":"price-modifier","example":"price-modifier","enum":["price-modifier"]},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"name":{"description":"A name for the modifier. You must give the price modifier a unique name. Price modifier names are case-sensitive","type":"string","example":"large-supplement","minLength":1,"x-go-name":"Name","nullable":true},"modifier_type":{"description":"There are three modifier types.\n\n* `price_increment` - Increases the price of a product.\n* `price_decrement` - Decreases the price of a product.\n* `price_equals` - Sets the price of a product to the amount you specify.\n","type":"string","example":"price_equals","enum":["price_equals","price_increment","price_decrement"],"x-go-name":"ModifierType","nullable":true},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true}},"additionalProperties":false}},"required":["id","type","attributes"],"additionalProperties":false,"x-go-name":"PriceModifierUpdate"}},"required":["data"],"additionalProperties":false,"x-go-name":"PriceModifierUpdateData"}}},"description":"The updated price modifier","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Updated price modifier.","content":{"application/json":{"schema":{"type":"object","title":"PriceModifierData","description":"Json-api style data object containing a single price modifier.","properties":{"data":{"type":"object","title":"PriceModifier","description":"A price modifier with the following attributes.","properties":{"type":{"type":"string","example":"price-modifier","default":"price-modifier","enum":["price-modifier"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique identifier associated with the price modifier. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"name":{"description":"A name for the modifier. You must give the price modifier a unique name. Price modifier names are case-sensitive.","type":"string","example":"large-supplement"},"modifier_type":{"description":"There are three modifier types.\n   * `price_increment` - Increases the price of a product.\n   * `price_decrement` - Decreases the price of a product.\n   * `price_equals` - Sets the price of a product to the amount you specify.\n","type":"string","example":"price_equals","enum":["price_equals","price_increment","price_decrement"]},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","modifier_type","currencies"]},"id":{"description":"A unique identifier for the price modifier.","type":"string","example":"37f2eed6-0bea-4d0b-a3c6-24cc76143bfd","x-go-name":"ID"},"meta":{"type":"object","properties":{"owner":{"description":"The product owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"PriceModifier"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/modifiers/f5bd1fc7-48a2-40ac-88dd-2bd9985050cd","nullable":true}},"title":"links-modifier"}},"required":["data"],"additionalProperties":false,"x-go-name":"PriceModifierData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The modifier already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Update a Price Book by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Price Book by ID"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/pricebooks/{pricebookID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates the specified price book. Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the price book is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"PricebookCreateData","properties":{"data":{"type":"object","title":"Pricebook","description":"Updates the specified price book.","properties":{"id":{"description":"The unique identifier of a price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"ID"},"type":{"description":"Always `pricebook`.","type":"string","x-go-name":"Type","default":"pricebook","example":"pricebook","enum":["pricebook"]},"attributes":{"type":"object","properties":{"description":{"description":"A brief description that describes a price book, for example, flash sale pricing or preferred customer pricing.","type":"string","example":"This is a price book","x-go-name":"Description","nullable":true},"name":{"description":"The name of a price book. Price books must have a unique name.","type":"string","example":"pricebook-store-abc","minLength":1,"x-go-name":"Name","nullable":true},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true}},"additionalProperties":false}},"required":["id","type","attributes"],"additionalProperties":false,"x-go-name":"PricebookUpdate"}},"required":["data"],"additionalProperties":false,"x-go-name":"PricebookUpdateData"}}},"description":"An updated price book with the following attributes.","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"An updated price book with the following attributes.","content":{"application/json":{"schema":{"type":"object","title":"PricebookData","description":"A price book with the following attributes.","properties":{"data":{"type":"object","title":"Pricebook","description":"A price book with the following attributes.","properties":{"id":{"description":"A unique identifier of a price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"ID"},"type":{"description":"Always `pricebook`.","type":"string","x-go-name":"Type","default":"pricebook","example":"pricebook","enum":["pricebook"]},"attributes":{"type":"object","properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"an-external-ref","x-go-name":"External Ref","nullable":true},"description":{"description":"A brief description that outlines the purpose of a price book, for example, flash sale pricing or preferred customer pricing.","type":"string","example":"This is a test price book","x-go-name":"Description","nullable":true},"name":{"description":"The name of a price book. Price books must have a unique name","type":"string","example":"Standard Price Book","x-go-name":"Name","nullable":true},"created_at":{"description":"The date and time when the price book was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price book was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"}},"required":["name","created_at","updated_at"]},"meta":{"type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true}}}},"required":["id","type","attributes"],"additionalProperties":false,"x-go-name":"Pricebook"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7","nullable":true}},"title":"links-pricebook"}},"required":["data"],"additionalProperties":false,"x-go-name":"PricebookData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price book already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Update a Product Price in a Price Book

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a Product Price in a Price Book"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/pricebooks/{pricebookID}/prices/{priceID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the price is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"pricebookID","in":"path","description":"The unique identifier of a price book.","required":true,"schema":{"type":"string"}},{"name":"priceID","in":"path","description":"A unique identifier of a price book price.","required":true,"schema":{"type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"ProductPriceData","description":"A product price with the following attributes.","properties":{"data":{"type":"object","title":"ProductPrice","properties":{"type":{"type":"string","example":"product-price","default":"product-price","enum":["product-price"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"sku":{"description":"The product SKU that the price belongs to.","type":"string","minLength":1,"example":"product-sku-a"},"sales":{"type":"object","description":"The sales price that an item is eligible for based on the price book.","example":{"summer":{"schedule":{"valid_form":"2023-12-24T09:00:00","valid_to":"2023-12-25T09:00:00"},"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"additionalProperties":{"type":"object","description":"The name of the sale, such as `Summer Sale`.","properties":{"bundle_ids":{"type":"array","description":"A list of product IDs in a bundle that you want to specify a sale price for.","items":{"type":"string","format":"uuid"},"x-omitempty":true,"x-go-name":"BundleIDs"},"schedule":{"type":"object","description":"The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n","properties":{"valid_from":{"description":"The start date of the sale.","type":"string","example":"2023-09-22T09:00:00Z","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"The end date of the sale.","type":"string","example":"2023-09-24T09:00:00Z","format":"date-time","x-go-name":"ValidTo","nullable":true},"rrule":{"type":"string","description":"Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n","example":"FREQ=WEEKLY;BYDAY=SA,SU","x-go-name":"RecurrenceRule","nullable":true},"tzid":{"type":"string","description":"Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n","example":"Europe/London","x-go-name":"Timezone","nullable":true}},"x-go-name":"Schedule","nullable":true,"title":"schedule"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"}},"title":"sale"},"title":"sales"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"created_at":{"description":"The date and time when the price was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"},"admin_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"admin-attributes"},"shopper_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"shopper-attributes"}},"required":["sku"]},"id":{"description":"The unique identifier for the product price.","type":"string","example":"a915553d-935d-4d56-870b-817b47a44a99","x-go-name":"ID"},"meta":{"description":"Information that provides context to other data sets.","type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true},"pricebook_id":{"description":"The unique identifier of the price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"Pricebook ID"}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"ProductPrice"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/prices/ad042b07-e86d-476a-82d5-43dda1f80d03","nullable":true}},"title":"links-price"}},"required":["data"],"additionalProperties":false,"x-go-name":"ProductPriceData"}}},"description":"The updated product price","required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"An updated product price with the following attributes.","content":{"application/json":{"schema":{"type":"object","title":"ProductPriceData","description":"A product price with the following attributes.","properties":{"data":{"type":"object","title":"ProductPrice","properties":{"type":{"type":"string","example":"product-price","default":"product-price","enum":["product-price"]},"pricebook_external_ref":{"description":"The unique attribute associated with the price book. This can be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string","example":"a-pricebook-external-ref","x-go-name":"Pricebook External Ref","nullable":true},"attributes":{"type":"object","properties":{"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"},"sku":{"description":"The product SKU that the price belongs to.","type":"string","minLength":1,"example":"product-sku-a"},"sales":{"type":"object","description":"The sales price that an item is eligible for based on the price book.","example":{"summer":{"schedule":{"valid_form":"2023-12-24T09:00:00","valid_to":"2023-12-25T09:00:00"},"currencies":{"USD":{"amount":90,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":40}}},"CAD":{"amount":117,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":80}}},"GBP":{"amount":65,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":50}}}}}},"additionalProperties":{"type":"object","description":"The name of the sale, such as `Summer Sale`.","properties":{"bundle_ids":{"type":"array","description":"A list of product IDs in a bundle that you want to specify a sale price for.","items":{"type":"string","format":"uuid"},"x-omitempty":true,"x-go-name":"BundleIDs"},"schedule":{"type":"object","description":"The schedule of the sale. If the entire `schedule` object is omitted or `null`, the sale price is considered permanent.\n\nWhen defining a recurring sale with `rrule`, the `valid_from` and `valid_to` parameters are mandatory to set the overall start and end dates for the recurrence. A single price cannot have both a standard and a recurring (`rrule`) sale schedule.\n\nYou can use `tzid` to set the timezone of the `valid_from` and `valid_to` parameters.\n\nFor sale prices within the same price book:\n  - The schedules must not be exactly the same.\n  - Schedules and recurrence rules can partially overlap. If schedules do overlap, the sale price active during the smallest sale period is chosen.\n  - If you have a single permanent sale price (no schedule), you must configure a schedule for it before adding other sale prices to the same price book.\n\n  \nSale prices in different price books can have overlapping schedules.\n","properties":{"valid_from":{"description":"The start date of the sale.","type":"string","example":"2023-09-22T09:00:00Z","format":"date-time","x-go-name":"ValidFrom","nullable":true},"valid_to":{"description":"The end date of the sale.","type":"string","example":"2023-09-24T09:00:00Z","format":"date-time","x-go-name":"ValidTo","nullable":true},"rrule":{"type":"string","description":"Specifies a recurring schedule for a sale, defined using a subset of the RFC 5545 RRULE format.\nThis allows for setting up sales that automatically apply on a recurring basis, such as weekly weekend discounts.\n\n**Supported RRULE Parameters:**\n  - `FREQ`: Defines the frequency of recurrence. Supported values: `WEEKLY`.\n  - `BYDAY`: Specifies the days of the week for weekly recurrences. Supported values: `MO`, `TU`, `WE`, `TH`, `FR`, `SA`, and `SU`.\n\n  \n**Example Usage:**\n  - Weekly sale on Saturdays and Sundays: `FREQ=WEEKLY;BYDAY=SA,SU`\n","example":"FREQ=WEEKLY;BYDAY=SA,SU","x-go-name":"RecurrenceRule","nullable":true},"tzid":{"type":"string","description":"Timezone based on the IANA Timezone Database (e.g., Europe/London or Europe/Paris).\nTimezones can be specified for both standard and `rrule` based sales.\nBy default, `valid_from` and `valid_to` are interpreted as UTC. Specifying a `tzid` applies that timezone to both the start and end dates.\n","example":"Europe/London","x-go-name":"Timezone","nullable":true}},"x-go-name":"Schedule","nullable":true,"title":"schedule"},"currencies":{"type":"object","description":"A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.","example":{"USD":{"amount":100,"includes_tax":false,"tiers":{"min_5":{"minimum_quantity":5,"amount":50}}},"CAD":{"amount":127,"includes_tax":false,"tiers":{"min_10":{"minimum_quantity":10,"amount":100}}},"GBP":{"amount":73,"includes_tax":true,"tiers":{"min_20":{"minimum_quantity":20,"amount":60}}}},"additionalProperties":{"type":"object","description":"The three-letter ISO code for the currency associated with this price.","properties":{"amount":{"description":"The price in the lowest denomination for the specified currency. This is a product's list price.","type":"integer","format":"int64","example":100,"x-go-name":"Amount","nullable":true},"includes_tax":{"description":"Whether this price includes tax.","type":"boolean","example":false,"default":false,"x-go-name":"IncludesTax"},"tiers":{"type":"object","description":"The price tier that an item is eligible for based on the quantity purchased. You cannot have conflicting tiers within the same currencies block.","additionalProperties":{"type":"object","description":"The name of the tier, for example, `Pencils`.","properties":{"minimum_quantity":{"description":"The minimum quantity of 1 or more defined for the specified price. If a minimum quantity is not specified, an error is returned.","type":"integer","format":"int64","example":"10","x-go-name":"MinQuantity","nullable":true},"amount":{"description":"The price for each quantity.","type":"integer","format":"int64","example":"50","x-go-name":"Amount","nullable":true}},"x-go-name":"TierPrice","title":"tier-price"}}},"title":"amount"},"title":"currencies"}},"title":"sale"},"title":"sales"},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"external-ref","x-go-name":"External Ref","nullable":true},"created_at":{"description":"The date and time when the price was created.","type":"string","format":"date-time","example":"2020-09-22T09:00:00Z","x-go-name":"CreatedAt"},"updated_at":{"description":"The date and time when the price was last updated.","type":"string","example":"2020-09-22T09:00:00Z","format":"date-time","x-go-name":"UpdatedAt"},"admin_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you may want to add custom attributes that can automate price updates based on predefined rules, saving time and reducing human error or you might want to integrate price attributes with your other company systems, (ERP, CRM) ensuring consistency and accuracy across platforms.\n \n`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add a `shopper_attribute`. \n \n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"admin-attributes"},"shopper_attributes":{"type":"object","description":"You can add custom attributes to a product price. For example, you can set prices based on customer segments. For instance, you can offer different prices for wholesale and retail customers or provide discounts to loyal customers. Following on from this, you might want to offer personalized offers and prices, enhancing the shopping experience.\n\n`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add an `admin_attribute`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"type":"string","nullable":true},"title":"shopper-attributes"}},"required":["sku"]},"id":{"description":"The unique identifier for the product price.","type":"string","example":"a915553d-935d-4d56-870b-817b47a44a99","x-go-name":"ID"},"meta":{"description":"Information that provides context to other data sets.","type":"object","properties":{"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","example":"store","nullable":true},"pricebook_id":{"description":"The unique identifier of the price book.","type":"string","example":"4c45e4ec-26e0-4043-86e4-c15b9cf985a7","x-go-name":"Pricebook ID"}}}},"required":["type","attributes","id"],"additionalProperties":false,"x-go-name":"ProductPrice"},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","format":"uri","example":"/pcm/pricebooks/4c45e4ec-26e0-4043-86e4-c15b9cf985a7/prices/ad042b07-e86d-476a-82d5-43dda1f80d03","nullable":true}},"title":"links-price"}},"required":["data"],"additionalProperties":false,"x-go-name":"ProductPriceData"}}}},"default":{"description":"Unexpected error.","content":{"application/json":{"schema":{"type":"object","title":"ErrorResponse","description":"This is a json-api style Error response","properties":{"errors":{"type":"array","items":{"type":"object","title":"ApiError","description":"This is a json-api style part of an error response","properties":{"detail":{"type":"string","example":"The price already exists","x-go-name":"Detail"},"status":{"type":"string","example":"409","x-go-name":"Status"},"title":{"type":"string","example":"conflict","x-go-name":"Title"}},"additionalProperties":false,"x-go-name":"ApiError"},"x-go-name":"Errors"}},"additionalProperties":false,"x-go-name":"ErrorResponse"}}}}}}
>
  
</StatusCodes>

---

## Attach Custom Relationships to a Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Attach Custom Relationships to a Product"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/{productID}/custom-relationships"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can attach up to 5 custom relationships to a product.  

Once you have attached a custom relationship to a product, you can then create relationships from a product to one or many other products. See [Associate a product to one or more products using a custom relationship](/docs/api/pxm/products/product-association-id). 

See [Custom Relationships](/guides/key-concepts/product-experience-manager/custom-relationships/).

### Prerequisites
  - A Custom Relationship has been created, see [create a Custom Relationship](/docs/api/pxm/products/create-custom-relationship),
  - A Product has been created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","type"],"properties":{"slug":{"type":"string","description":"The slug of the custom relationship."},"type":{"type":"string","enum":["custom-relationship"],"description":"This represents the type of resource. Always `custom-relationship`."}}}}},"title":"attach_custom_relationship_request"},"examples":{"assign-custom-relationships-to-product":{"summary":"attach custom relationships to product","value":{"data":[{"type":"custom-relationship","slug":"CRP_related_products"},{"type":"custom-relationship","slug":"CRP_cart_products"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Returns the attached custom relationships","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a custom relationship is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `custom-relationship`.","type":"string","enum":["custom-relationship"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"description":"The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.","type":"string","example":"Related Products"},"description":{"description":"A description of the custom relationship.","type":"string","example":"A list of related products shown on the PDP."},"slug":{"description":"A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string","example":"CRP_related_products","pattern":"^[A-Za-z0-9._-]+$"},"sort_order":{"description":"The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5},"external_name":{"description":"The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.","nullable":true,"type":"string","example":"Similar items to consider"},"external_description":{"description":"The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.","nullable":true,"type":"string","example":"Check out these similar products that may also meet your needs or match your preferences."},"bi_directional":{"type":"boolean","description":"Is this relationship one way or bi-directional `true` or `false`. Default is false","default":false}},"title":"req_attributes_custom_relationship"},"meta":{"type":"object","required":["owner","timestamps"],"properties":{"owner":{"description":"The owner of the resource.","type":"string","example":"store"},"timestamps":{"type":"object","required":["created_at","updated_at"],"properties":{"created_at":{"description":"The date and time the resource is created.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"},"updated_at":{"description":"The date and time the resource is updated.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"}}}}}},"title":"custom_relationship"}},"links":{"type":"object","description":"Links are used to allow you to move between requests.","properties":{"first":{"description":"Always the first page.","type":"string","example":"/pcm/custom_relationships?page[offset]=0&page[limit]=10"},"last":{"description":"This is `null` if there is only one page.","type":"string","example":"/pcm/custom_relationships?page[offset]=20&page[limit]=10"},"next":{"description":"This is `null` if there is only one page.","type":"string","example":"/pcm/custom_relationships?page[offset]=10&page[limit]=10"},"prev":{"description":"This is `null` if you on the first page.","type":"string","example":"/pcm/custom_relationships?page[offset]=8&page[limit]=10"}},"title":"multi_links_cr"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"}},"title":"multi_custom_relationships"},"examples":{"custom-relationship":{"summary":"Attached custom relationships","value":{"data":[{"id":"f3297ee8-da90-45e9-ae56-a2654aebbdfe","type":"custom-relationship","attributes":{"name":"Kitchen electrics","description":"Kitchen electric devices","slug":"CRP_kitchen_individual_devices","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}},{"id":"21b1315b-c47f-4766-85bf-7bf0f94d73b6","type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","bi_directional":true},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}},{"id":"e390ff7e-efc4-4769-90d2-fceabcc1e2cd","type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","sort_order":5,"external_name":"Similar items to consider","external_description":"Check out these similar products that may also meet your needs or match your preferences.","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}}],"links":{"last":"/pcm/custom_relationships?page[offset]=29&page[limit]=1","next":"/pcm/custom_relationships?page[offset]=1&page[limit]=1"},"meta":{"results":{"total":3}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Attach multiple nodes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Attach multiple nodes"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/attach_nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Assigns products to multiple hierarchies and their children nodes. You can apply a filter to search for the appropriate products to attach to a node. For general filtering syntax, see [**Filtering**](/guides/Getting-Started/filtering).
 
 The following attributes and operators are supported.
 
 | Operator                  | Attribute                                                                                                                                               | Description                                                                                                                                                                                                                                             | Example                                          |
 | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------- |
 | `eq`                      | `id`, `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `name`, `templates`, `commodity_type`, `owner`, `product_types`, `parent_id`, `component_option_id`, `tags`, `status`, `has_nodes (false only)`, `created_at`, `updated_at`, `external_ref`, `description` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. For `product_types`, you can only specify one product type. **Note:** `has_nodes` can only be filtered as `false`. **Note:** `component_option_id` matches when a bundle includes that product id as a component option. | `?filter=eq(name,some-name)` |
 | `like`                    | `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `name`, `tags`, `description`, `external_ref`                                                        | Like. Checks if the operand contains the specified string. Wildcards are supported.                                                                                                                                                                     | `?filter=like(name,*some-name*)`                 |
 | `in`                      | `id`, `name`, `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `product_types`, `parent_id`, `component_option_id`, `tags`, `external_ref`                                   | Checks if the values are included in the specified list. If they are, the condition is true. For `product_types`, you can specify more than one product type.                                                                                           | `?filter=in(id,some-id)`                         |
 | `gt`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Greater than. Checks if the value of the field is greater than the given value.                                                                                                                                                                         | `?filter=gt(updated_at,2024-01-01T00:00:00Z)`    |
 | `ge`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Greater than or equal to. Checks if the value of the field is greater than or equal to the given value.                                                                                                                                                 | `?filter=ge(created_at,2023-01-01T00:00:00Z)`    |
 | `lt`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Less than. Checks if the value of the field is less than the given value.                                                                                                                                                                               | `?filter=lt(updated_at,2025-01-01T00:00:00Z)`    |
 | `le`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Less than or equal to. Checks if the value of the field is less than or equal to the given value.                                                                                                                                                       | `?filter=le(created_at,2022-01-01T00:00:00Z)`    |
 | `eq` (extensions)         | `extensions.book.isbn`                                                                                                                                  | Filters using a nested extension field.                                                                                                                                                                                                                 | `?filter=eq(extensions.book.isbn,1765426)`       |
 | `eq` (shopper_attributes) | `shopper_attributes.color`                                                                                                                              | Filters using a shopper custom attribute field.                                                                                                                                                                                                         | `?filter=eq(shopper_attributes.color,red)`       |
 | `eq` (admin_attributes)   | `admin_attributes.warehouse`                                                                                                                            | Filters using an admin custom attribute field.                                                                                                                                                                                                          | `?filter=eq(admin_attributes.warehouse,US-EAST)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["filter","node_ids"],"properties":{"filter":{"type":"string","description":"Filters applied to search for appropriate products to attach to a node. See [Attach multiple nodes](/docs/api/pxm/products/attach-nodes).\n","example":"eq(sku,book)"},"node_ids":{"type":"array","description":"A list of node unique identifiers that you want to assign to the products.","example":["123"],"items":{"type":"string"}}}}}},"examples":{"product-attach-nodes":{"summary":"Attach multiple nodes","value":{"data":{"filter":"eq(sku,book)","node_ids":["123"]}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"This request assigns the products that you have selected to multiple hierarchies and their children nodes and returns the following.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"nodes_attached":{"description":"Number of nodes assigned to the products.","type":"integer"},"nodes_not_found":{"type":"array","description":"A list of node unique identifiers that could not be identified.","example":["123"],"items":{"type":"string"}}}}}},"examples":{"created-product":{"summary":"Attach multiple nodes","value":{"meta":{"nodes_attached":3,"nodes_not_found":[]}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Build child products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Build child products"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/{productID}/build"}
  context={"endpoint"}
>
  
</MethodEndpoint>

With product variations in Product Experience Manager, you can create product variations and different options for each variation and use both to create child products for a product. Each child product is a unique combination of options associated with the product.  

Child products inherit attributes from their parent products. When you make changes to the attributes of the parent products, you can rebuild your child products, ensuring that changes to the parent products are propagated to the child products.

Alternatively, you can modify a child product independently, without impacting its parent product. For example, you may prefer the status of your child product to be `live`, while keeping the parent product's status as `draft`. When you directly update a child product, it becomes independent of its parent product. In other words, any subsequent changes made to the parent product are not automatically reflected in the child product when you rebuild the parent product and its child products. Once a child product is independent of its parent, you cannot recreate the association between the child product and its parent. You must delete the child product and rebuild the parent to recreate the child product.

Following on from that, if you add the same flow to both a parent and child product, the child flow values are not affected by changes to the parent flow values in a rebuild.

### Using Build Rules

When building your child products, you can build all products related to a product. 

Alternatively, you can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. You can do this using `build_rules`. `build_rules` are combinations of variation option IDs that you wish to include or exclude when building your child products.

:::note

You do not need to configure any `build_rules` in the following scenarios:

- Child products must be built with all variation options. Simply, use the `Create a product` or `Update a product` endpoints with no `build_rules` specified.
- Child products must be built apart from all options for a specific variation. In this case, you must remove the variation and use the `Create a product` or `Update a product` endpoints with no `build_rules` specified. In other words, using our example, if none of the `size` options should be included, then remove the `size` variation.

:::

The `build_rules` contain:

- (Required) `default`: specifies the default behavior.
- (Optional) `include`: specifies the option IDs to include when the child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations. See [**Invalid Build Rules**](#invalid-build-rules).
- (Optional) `exclude`: specifies the option IDs to exclude when the child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations. See [**Invalid build rules**](#invalid-build-rules).

When building child products, Commerce compares each combination of option IDs to these rules to determine how your child products should be built, depending on how you have configured the `build_rules`. It depends on your requirements how you configure your `build_rules`.

#### Invalid Build Rules

The `build_rules` are invalid if both the option IDs come from the same variation. Combinations of option IDs in the nested arrays must come from different variations.

If Commerce cannot resolve the `build_rules` a `could not determine whether to include or exclude a child product due to ambiguous rules` error is returned. This error can occur, for example, if you have the same number of variation option IDs in both the `include` and `exclude` arrays and the variation option IDs match.

### Building Child Products

Building child products is an asynchronous operation. When you build child products, a job is created. The jobId of the job is displayed in the response. When the job is complete, the build child products operation is also complete. You can use the jobId to see the status of your job using the `Get a Job` endpoint.

Jobs are processed one at a time. You can continue to send build child product requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See Jobs.

Re-building child products after adding or removing a new variation changes the total number of child products that you can generate from a parent product. When you rebuild the child products after updating variations associated with the parent product, all existing child products that belong to a parent product are deleted. New child products are created with new product IDs.

If you have any bundles that reference child products directly, then you must update the bundles with the new child product IDs.

However, re-building child products after adding or removing an option does not change the existing product IDs.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully started building child products","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a job is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `pim-job`.","type":"string","enum":["pim-job"]},"attributes":{"type":"object","required":["started_at","completed_at","created_at","updated_at","type","status"],"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true},"completed_at":{"type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true,"description":"The date and time a job is completed."},"created_at":{"type":"string","description":"The date and time a job is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a job is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"type":{"type":"string","description":"The status of a job.\n\n* `pending` - Commerce has received the request but is currently busy processing other requests.\n* `started` - Commerce has started processing the job.\n* `success` - The job has successfully completed.\n* `failed` - The job has failed.\n","enum":["child-products","product-import","product-export","hierarchy-duplicate","pricebook-import","pricebook-delete","hierarchy-delete","indexing-job","attach-nodes"]},"status":{"type":"string","enum":["pending","cancelled","cancelling","started","success","failed"]}}},"meta":{"type":"object","required":["x_request_id"],"properties":{"x_request_id":{"type":"string","description":"Applies to all job types. A unique request ID is generated when a job is created."},"copied_from":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated."},"hierarchy_id":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID."},"file_locations":{"type":"array","nullable":true,"description":"If the job type is `product_export`, a link to the file is created when running a job.","items":{"type":"string"}},"filter":{"type":"string","nullable":true,"description":"The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export."}}}},"title":"job"}},"title":"single"},"examples":{"build-child-products":{"value":{"data":{"type":"pim-job","id":"dcc9e0bb-526b-4207-9e52-081589cdb50e","attributes":{"completed_at":null,"created_at":"2024-11-01T14:11:00.917Z","started_at":null,"status":"pending","type":"child-products","updated_at":"2024-11-01T14:11:00.917Z"},"meta":{"x_request_id":"85609bc9-6f19-4831-919a-a5b43e662061"}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Bundle Component Products Relationships

With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together.

You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Cancel a Job(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cancel a Job"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/jobs/{jobID}/cancel"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The jobs endpoints display the status of a number of endpoints that function as jobs, for example, product import and export, and duplicating hierarchies.

Jobs are processed one at a time. You can continue to send job requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. If you decide that a specific job needs to be prioritized over another, you can cancel the less critical job using the `Cancel a job` endpoint. You can only cancel jobs whose status is PENDING.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"jobID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the job."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully cancelled job","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a job is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `pim-job`.","type":"string","enum":["pim-job"]},"attributes":{"type":"object","required":["started_at","completed_at","created_at","updated_at","type","status"],"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true},"completed_at":{"type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true,"description":"The date and time a job is completed."},"created_at":{"type":"string","description":"The date and time a job is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a job is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"type":{"type":"string","description":"The status of a job.\n\n* `pending` - Commerce has received the request but is currently busy processing other requests.\n* `started` - Commerce has started processing the job.\n* `success` - The job has successfully completed.\n* `failed` - The job has failed.\n","enum":["child-products","product-import","product-export","hierarchy-duplicate","pricebook-import","pricebook-delete","hierarchy-delete","indexing-job","attach-nodes"]},"status":{"type":"string","enum":["pending","cancelled","cancelling","started","success","failed"]}}},"meta":{"type":"object","required":["x_request_id"],"properties":{"x_request_id":{"type":"string","description":"Applies to all job types. A unique request ID is generated when a job is created."},"copied_from":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated."},"hierarchy_id":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID."},"file_locations":{"type":"array","nullable":true,"description":"If the job type is `product_export`, a link to the file is created when running a job.","items":{"type":"string"}},"filter":{"type":"string","nullable":true,"description":"The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export."}}}},"title":"job"}},"title":"single"},"examples":{"cancelled":{"summary":"Cancelled Job","value":{"data":{"type":"pim-job","id":"1e5da4bf-b2c0-4619-bb3d-f749875b15bb","attributes":{"started_at":null,"completed_at":null,"created_at":"2023-11-14T15:37:13.589Z","status":"cancelled","type":"product-import","updated_at":"2023-11-14T15:37:13.589Z"},"meta":{"x_request_id":"4fde01c1-95ba-4dd6-948e-b9d5763ff9c2"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a custom relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a custom relationship"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/custom-relationships"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Custom relationships can either be bi-directional or uni-directional.
  - **Uni-Directional**: By setting `bi_directional` to `false` (or omitted from request) a uni-directional custom relationship will be created. 
  Within a uni-directional relationship, if Product A links to Product B, Product B will not link back to Product A. 
  This is ideal when one product (e.g., a base product) recommends another (e.g., an upsell), but the reverse 
  recommendation is unnecessary.
 
 - **Bi-Directional**: By setting `bi_directional` to `true` a bi-directional custom relationship will be created. Within a bi-directional 
 relationship, if Product A is linked to Product B, Product B will automatically link back to Product A. 
 This bi-directionality ensures a consistent experience, where products always suggest each other as related items.
 
  For more information on use cases, see [Custom Relationships](/guides/key-concepts/product-experience-manager/custom-relationships/).

Custom Relationship slugs must meet the following criteria:
  - be unique 
  - be prefixed with `CRP_`. Product Experience Manager automatically adds the `CRP_` prefix if you do not include it.
  - contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.
 
Once a custom relationship has been created, you can then create Product Relationships:
   1. Add the custom relationship to a product. See [Attach a custom relationship to a product](/docs/api/pxm/products/attach-custom-relationships).
   2. Associate a product to multiple products. See [Associate a product with other products under a custom relationship](/docs/api/pxm/products/product-association-id).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `custom-relationship`.","type":"string","enum":["custom-relationship"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"description":"The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.","type":"string","example":"Related Products"},"description":{"description":"A description of the custom relationship.","type":"string","example":"A list of related products shown on the PDP."},"slug":{"description":"A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string","example":"CRP_related_products","pattern":"^[A-Za-z0-9._-]+$"},"sort_order":{"description":"The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5},"external_name":{"description":"The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.","nullable":true,"type":"string","example":"Similar items to consider"},"external_description":{"description":"The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.","nullable":true,"type":"string","example":"Check out these similar products that may also meet your needs or match your preferences."},"bi_directional":{"type":"boolean","description":"Is this relationship one way or bi-directional `true` or `false`. Default is false","default":false}},"title":"req_attributes_custom_relationship"}}}},"title":"create_custom_relationship"},"examples":{"create-basic-custom-relationship":{"summary":"Basic","description":"Create a custom relationship with minimal fields.","value":{"data":{"type":"custom-relationship","attributes":{"name":"Kitchen electrics","description":"Kitchen electric devices","slug":"CRP_kitchen_individual_devices"}}}},"create-custom-relationship-external-sort-order":{"summary":"External Name and Description, and Sort Order","description":"Create a custom relationship with an external name and description, as well as specifying a sort order.","value":{"data":{"type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","sort_order":5,"external_name":"Similar items to consider","external_description":"Check out these similar products that may also meet your needs or match your preferences."}}}},"create-custom-relationship-bi-directional":{"summary":"Bi-Directional","description":"Create a custom relationship with bi-directional relationships.","value":{"data":{"type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","bi_directional":true}}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Returns a created custom relationship with the following attributes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a custom relationship is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `custom-relationship`.","type":"string","enum":["custom-relationship"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"description":"The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.","type":"string","example":"Related Products"},"description":{"description":"A description of the custom relationship.","type":"string","example":"A list of related products shown on the PDP."},"slug":{"description":"A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string","example":"CRP_related_products","pattern":"^[A-Za-z0-9._-]+$"},"sort_order":{"description":"The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5},"external_name":{"description":"The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.","nullable":true,"type":"string","example":"Similar items to consider"},"external_description":{"description":"The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.","nullable":true,"type":"string","example":"Check out these similar products that may also meet your needs or match your preferences."},"bi_directional":{"type":"boolean","description":"Is this relationship one way or bi-directional `true` or `false`. Default is false","default":false}},"title":"req_attributes_custom_relationship"},"meta":{"type":"object","required":["owner","timestamps"],"properties":{"owner":{"description":"The owner of the resource.","type":"string","example":"store"},"timestamps":{"type":"object","required":["created_at","updated_at"],"properties":{"created_at":{"description":"The date and time the resource is created.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"},"updated_at":{"description":"The date and time the resource is updated.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"}}}}}},"title":"custom_relationship"}},"title":"single_custom_relationship"},"examples":{"created-basic-custom-relationship":{"summary":"Basic","value":{"data":{"id":"f3297ee8-da90-45e9-ae56-a2654aebbdfe","type":"custom-relationship","attributes":{"name":"Kitchen electrics","description":"Kitchen electric devices","slug":"CRP_kitchen_individual_devices","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}}}},"created-custom-relationship-external-sort-order":{"summary":"External name and description, and sort order","value":{"data":{"id":"e390ff7e-efc4-4769-90d2-fceabcc1e2cd","type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","sort_order":5,"external_name":"Similar items to consider","external_description":"Check out these similar products that may also meet your needs or match your preferences.","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}}}},"created-custom-relationship-bi-directional":{"summary":"Bi-Directional","value":{"data":{"id":"e390ff7e-efc4-4769-90d2-fceabcc1e2cd","type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","bi_directional":true},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}}}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create relationships between a hierarchy and child nodes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create relationships between a hierarchy and child nodes"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/hierarchies/{hierarchyID}/relationships/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to create relationships between a hierarchy and one or more child nodes. You can create a relationship only if:

- All child nodes already exist.
- Every child node in the request body must belong to this hierarchy.
- All siblings in a hierarchy must have a unique `name` and `slug`. Siblings are the child nodes that are related to the same parent.

### Sort Order

You can also provide `sort_order` information when you create a relationship by adding a `meta` object to the array of node reference objects for each child node that requires sorting.

The node with the highest value of `sort_order` appears at the top of the response. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`.

- If you don’t provide `sort_order` when creating relationships, all child nodes in the response for Get a Hierarchy’s Children request are ordered by the `updated_at` time in descending order. The most recently updated child node appears at the top of the response.
- If you set `sort_order` for only a few child nodes or not all, the child nodes with `sort_order` value appear first in the response and then other child nodes appear in the order of `updated_at` time.

You can also specify a `sort_order` when creating and updating a node.

- If you create or update a node (**Node A**) with a `sort_order` and then you create a relationship for **Node A** with hierarchy (**Hierarchy A**) with a new `sort_order`, the `sort_order` you specified when creating\updating **Node A** is overwritten.
- If you create\update **Node A** and then you create a relationship with **Hierarchy A** but do not configure a `sort_order`, the `sort_order` you specified when you created\updated **Node A** is not overwritten.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier of the child node. Must not match the node ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]}}}}},"title":"node_children"},"examples":{"set-node-children":{"value":{"data":[{"type":"node","id":"b2f5e53e-de3c-4548-98da-120f8b185d34"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the hierarchy","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","meta","relationships","attributes"],"properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description for a hierarchy.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes_hierarchy"},"relationships":{"type":"object","properties":{"children":{"description":"The child nodes related to the hierarchy.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships_hierarchy"},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a hierarchy is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the hierarchy has child nodes.","type":"boolean"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"hierarchy"}},"title":"single_hierarchy"},"examples":{"set-node-children":{"value":{"data":{"type":"hierarchy","id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","attributes":{"description":"Shoes Category Updated","locales":{"fr-FR":{"name":"Chaussures mises à jour","description":"Catégorie de chaussures mise à jour"}},"admin_attributes":{"cost_of_goods":"42.0"},"shopper_attributes":{"charge_type":"credit card"},"name":"Shoes Updated","slug":"shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/children"}}},"meta":{"created_at":"2024-01-10T20:16:35.343Z","owner":"store","updated_at":"2024-01-10T20:30:50.867Z","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes Updated","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}}]}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a hierarchy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a hierarchy"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/hierarchies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

```mdx-code-block
import CASummary from '/docs/partials/pxm/custom-attributes/custom-attribute-spec-summary.mdx';

Creates a hierarchy with a name, description, and slug to organize products in your catalog.

<CASummary />
```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The name of the hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description of the hierarchy.","type":"string"},"slug":{"description":"A unique slug for the hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized name for the hierarchy.","type":"string"},"description":{"description":"A localized description for the hierarchy.","type":"string"}}}}},"title":"req_attributes_hierarchy"}}}},"title":"create_hierarchy"},"examples":{"create-hierarchy":{"value":{"data":{"type":"hierarchy","attributes":{"name":"Shoes","description":"Shoes Category","slug":"shoes","admin_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"shopper_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"locales":{"fr-FR":{"name":"Chaussures","description":"Catégorie de chaussures"}}}}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Returns a created hierarchy with the following attributes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","meta","relationships","attributes"],"properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description for a hierarchy.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes_hierarchy"},"relationships":{"type":"object","properties":{"children":{"description":"The child nodes related to the hierarchy.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships_hierarchy"},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a hierarchy is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the hierarchy has child nodes.","type":"boolean"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"hierarchy"}},"title":"single_hierarchy"},"examples":{"created-hierarchy":{"value":{"data":{"type":"hierarchy","id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","attributes":{"description":"Shoes Category","locales":{"fr-FR":{"name":"Chaussures","description":"Catégorie de chaussures"}},"admin_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"shopper_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"name":"Shoes","slug":"shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/children"}}},"meta":{"created_at":"2024-01-10T20:16:35.343Z","owner":"store","updated_at":"2024-01-10T20:16:35.343Z","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}}]}}}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a modifier(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a modifier"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/variations/{variationID}/options/{optionID}/modifiers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product.
 
The table below describes the different types of modifiers.

| Modifier | Data Type | Effect |
| :--- | :--- | :--- |
| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |
| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |
| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |
| `description_equals` | `string` | Overrides the description of the child product. |
| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |
| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |
| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |
| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |
| `price_increment` | `string` | Increases the price of the child product. |
| `price_decrement` | `string` | Decreases the price of the child product. |
| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |
| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `"seek": :{COLOR}"`. |
| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `"seek": :{COLOR}"`. |
| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `"seek": :{COLOR}"`. |
| `sku_equals` | `string` | Sets the SKU of the child product. |
| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |
| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |
| `sku_builder` | `string` | Sets a part of the SKU of the child product. |
| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"optionID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the option."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","description":"Use modifiers to change the properties of child products that are inherited from a parent product. With modifiers, you only need to have one parent product with a variation attached to the product.","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `product-variation-modifier`.","type":"string","enum":["product-variation-modifier"]},"attributes":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","description":"You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. See [Create a Modifier](/docs/api/pxm/products/create-modifier).\n","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"description":"Required for non-builder modifiers. The value of the modifier type.","type":"string"},"seek":{"description":"Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.","type":"string"},"set":{"description":"Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.","type":"string"},"reference_name":{"description":"A name for the modifier.","type":"string"}}}}}},"title":"create_modifier"},"examples":{"create-variation-modifier":{"value":{"data":{"type":"product-variation-modifier","attributes":{"seek":"{color}","set":"red","type":"slug_builder"}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully returns the created modifier","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"A unique identifier for a modifier that is generated automatically when a modifier is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation-modifier`.","type":"string","enum":["product-variation-modifier"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"type":{"description":"You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n","type":"string","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"description":"Required for non-builder modifiers. The value of the modifier type.","type":"string"},"seek":{"description":"Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.","type":"string"},"set":{"description":"Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.","type":"string"},"reference_name":{"description":"The name of the modifier.","type":"string"}}},"meta":{"type":"object","properties":{"owner":{"description":"The owner of the resource, either `organization` or `store`.","type":"string","enum":["organization","store"]}}}}}},"title":"created_modifier"},"examples":{"created-variation-modifier":{"value":{"data":{"type":"product-variation-modifier","id":"a510cddc-e946-4c22-9541-54626a7cf0ec","attributes":{"seek":"{color}","set":"red","type":"slug_builder"},"meta":{"owner":"store"}}}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create relationships between a node and child nodes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create relationships between a node and child nodes"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}/relationships/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use this endpoint to create relationships between a single parent node and one or more child nodes. You can create a relationship only if:

- The parent node already exists.
- All child nodes already exist.
- Every child node in the body of the request exists in the same hierarchy as the parent node.
- A node is not a parent of itself. An array of child nodes request body must not contain the ID of the parent node in the path.
- All siblings in a hierarchy must have a unique `slug`. Siblings are the child nodes that are related to the same parent.

### Sort Order

You can also provide `sort_order` information when you create a relationship by adding a `meta` object to the array of node reference objects for each child node that requires sorting.

The node with the highest value of `sort_order` appears at the top of the response. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`.

- If you don’t provide `sort_order` when creating relationships, all child nodes in the response for Get a Node’s Children request are ordered by the `updated_at` time in descending order. The most recently updated child node appears at the top of the response.
- If you set `sort_order` for only a few child nodes or not all, the child nodes with `sort_order` value appear first in the response and then other child nodes appear in the order of `updated_at` time.

You can also specify a `sort_order` when creating and updating a node.

- If you create or update a node (**Node A**) with a `sort_order` and then you create a relationship for **Node A** with another node (**Node B**) with a new `sort_order`, the `sort_order` you specified when creating\updating **Node A** is overwritten.
- If you create\update **Node A** and then you create a relationship with **Node B** but do not configure a `sort_order`, the `sort_order` you specified when you created\updated **Node A** is not overwritten.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier of the child node. Must not match the node ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]}}}}},"title":"node_children"},"examples":{"set-node-children":{"value":{"data":[{"type":"node","id":"b2f5e53e-de3c-4548-98da-120f8b185d34"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the parent node","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"title":"single_node"},"examples":{"set-node-children":{"value":{"data":{"type":"node","id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"admin_attributes":{"cost_of_goods":"42.0"},"shopper_attributes":{"charge_type":"credit card"},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a node's product relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a node's product relationships"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}/relationships/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates relationships between the specified node and one or more products in a specified hierarchy.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier of the product to be attached to the node.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]}}}}},"title":"node_products"},"examples":{"create-node-product-relationships":{"value":{"data":[{"type":"product","id":"9c85b276-09b4-488e-a59c-c561bae14c9e"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully returns the updated node","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"title":"single_node"},"examples":{"created-node-product-relationships":{"value":{"data":{"type":"node","id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"admin_attributes":{"cost_of_goods":"42.0"},"shopper_attributes":{"charge_type":"credit card"},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a node

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a node"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

```mdx-code-block
import CASummary from '/docs/partials/pxm/custom-attributes/custom-attribute-spec-summary.mdx';

Creates a node in the specified hierarchy.

<CASummary />         
```

 ### Sorting Nodes in a Hierarchy
  
 You can sort the order of your nodes, regardless of where the nodes are in the hierarchy.

 You can do this by adding a `meta` object to the body of your request and specifying a `sort_order` value.
  
 The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`.

 - If you don’t provide `sort_order` when creating nodes, all child nodes in the response for Get a Node’s Children request are ordered by the `updated_at` time in descending order, with the most recently updated child node first.
 - If you set `sort_order` for only a few child nodes, the child nodes with a `sort_order` value appear first and then other child nodes appear in the order of `updated_at` time.

 You can also specify a `sort_order` when creating a node relationship.

 - If you create a node (**Node A**) with a `sort_order` and then you create a relationship for **Node A** with another node (**Node B**), the `sort_order` you specified when creating **Node A** is overwritten.
 - If you create **Node A** and then you create a relationship with **Node B** but do not configure a `sort_order`, the `sort_order` you specified when you created **Node A** is not overwritten.
  
 ### Curating Products in a Node
  
  You can curate the products in a node. Product curation allows you to promote specific products within each node of your hierarchies, enabling you to create unique product collections in your storefront. For example, you may find you have an abundance of cotton T-Shirts and you want to promote these products to the top of the product list. When a shopper navigates to T-shirts, the cotton T-Shirts are displayed first.
  
  You can do this by adding a `curated_products` attribute to the body of your request and adding an array of product IDs to the attribute. You should add the products IDs in the order you want them to be displayed in your node. The first product ID is displayed first in the product list.
  
  You can only curate 20 products or less. You cannot have more than 20 curated products.
  
  - The product IDs you provide must exist in the specified node.
  - If a curated product is removed from a node, the product is also removed from the curated_products list.
  - Once you have curated the products in a node, you can use the get node products endpoint to retrieve a list of curated products.
  
  You can then display your curated products in your catalogs using the following catalog endpoints.
  
  - Get a node in your latest catalog release.
  - Get a node in a catalog.
  - Get all nodes in your latest catalog release.
  - Get all nodes in a catalog.
  - Get node children in your latest catalog release.
  - Get node children in a catalog.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description of the node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront. See [Curating Products in a Node](/docs/api/pxm/products/create-node#curating-products-in-a-node).","type":"array","items":{"description":"A list of product IDs for the products that you want to curate in a node.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized name for the node.","type":"string"},"description":{"description":"A localized description for the node.","type":"string"}}}}},"title":"attributes_nodes"},"meta":{"type":"object","additionalProperties":false,"properties":{"sort_order":{"description":"You can sort the order of your nodes, regardless of where the nodes are in the hierarchy. The `sort_order` for each node. This value determines the order of nodes in the response for the `Get a Node’s Children` request. The node with the highest value of sort_order is displayed first. For example, a node with a sort_order value of 3 appears before a node with a sort_order value of 2.\n\n- If you don’t provide `sort_order` when creating nodes, all child nodes in the response for `Get a Node’s Children` request are ordered by the `updated_at` time in descending order, with the most recently updated child node first.\n- If you set `sort_order` for only a few child nodes or not all, the child nodes with a `sort_order` value appear first and then other child nodes appear in the order of `updated_at` time. See [Sorting Nodes in a hierarchy]().\n","type":"integer"}}}}}},"title":"create_node"},"examples":{"create-node":{"value":{"data":{"type":"node","attributes":{"name":"Ballet Shoes","description":"All Ballet Shoes","slug":"ballet-shoes","admin_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"shopper_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Toutes les ballerines"}}},"meta":{"sort_order":2}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully returns the created node","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"title":"single_node"},"examples":{"created-node":{"value":{"data":{"type":"node","id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","attributes":{"description":"All Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Toutes les chaussures de ballet"}},"admin_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"shopper_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"parent":{"data":{"type":"node","id":"14e8e15a-7214-435d-bccb-6ae9b570d683"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","parent_name":"Shoes","sort_order":2,"updated_at":"2024-01-11T19:19:50.087Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a product file relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a product file relationship"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/{productID}/relationships/files"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a product file relationship

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a file generated when a file is created.","type":"string"},"type":{"description":"This represents the type of resource being returned. Always `file`.","type":"string","enum":["file"]},"meta":{"type":"object","properties":{"tags":{"description":"The files associated with a product.","type":"array","items":{"type":"string"}}},"additionalProperties":false}}}}},"title":"product_files_request"},"examples":{"create-product-file-relationship":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"file"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"file"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create main image relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create main image relationships"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/{productID}/relationships/main_image"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Associates a main image with the specified product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the image file.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource being returned. Always `file`.","type":"string","enum":["file"]}}}},"title":"main_image_request"},"examples":{"create-product-main-image-relationship":{"value":{"data":{"type":"file","id":"3ab3deca-1f11-47b7-a409-24ea3234d72c"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a product template relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a product template relationship"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/{productID}/relationships/templates"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all the templates that are associated with the specified product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of a template."},"type":{"type":"string","enum":["template"],"description":"This represents the type of resource object being returned. Always `template`."}}}}},"title":"product_templates_request"},"examples":{"create-product-template-relationship":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"template"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"template"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Returns a created product template relationship.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a template generated when a template is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `template`.","type":"string","enum":["template"]}}}}},"title":"template_response"},"examples":{"product-templates":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"template"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"template"}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a product variation relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a product variation relationship"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/{productID}/relationships/variations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a product variation relationship

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the product variation."},"type":{"type":"string","enum":["product-variation"],"description":"This represents the type of resource being returned. Always `product-variation`."}}}}},"title":"product_variations_request"},"examples":{"create-product-variation-relationship":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"product-variation"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a product or bundle

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a product or bundle"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a product or bundle with the attributes that are defined in the body.

#### Product Types

Product Experience Manager automatically assigns types to the products you create. You can filter on product types. Product types can also be used in catalogs. For example, in your catalog, you can filter on `parent` so that only your parent products are displayed in your storefront. 

See [**Product Types**](/docs/api/pxm/products/products#product-types).

#### Product Tags

You can use product tags to store or assign a key word against a product or service that you sell in your store. The product tag can then be used to describe or label that product. Product tags represent similarities between products who do not share the same attributes. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. 

See [**Product Tags**](/docs/api/pxm/products/product-tags).

#### Personalizing Products

You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized, or you sell greetings cards that can be printed with your shoppers personalized messages. You can do this by configuring the `custom_inputs` attribute.

When configuring the `custom_inputs` attribute:

- You can rename `input` to something more representative of the input that shoppers are adding, for example, `message` or `front`.
- `name` is the name that is displayed in your storefront.
- You can add validation rules. For example, the input field must be a `string` and/or up to 255 characters in length. The limit is 255 characters.
- You can specify if the input field is required.

#### Curating Products

You can curate the products in a node. Product curation allows you to promote specific products within each node of your hierarchies, enabling you to create unique product collections in your storefront. For example, you may find you have an abundance of cotton T-Shirts and you want to promote these products to the top of the product list. When a shopper navigates to T-shirts, the cotton T-Shirts are displayed first. See [**Update a node**](/docs/api/pxm/products/update-node).

#### Bundles

With Product Experience Manager, you can use the products API to create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. 

See [**Bundles**](/docs/api/pxm/products/products#bundles).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"This represents the type of resource being returned. Always `product`.","type":"string","enum":["product"],"example":"product"},"attributes":{"type":"object","additionalProperties":false,"properties":{"external_ref":{"type":"string","description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters."},"name":{"type":"string","description":"The product name to display to customers."},"description":{"description":"A description for the product.","type":"string"},"slug":{"type":"string","description":"The unique slug of the product. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed."},"sku":{"type":"string","description":"The unique stock keeping unit of the product."},"status":{"type":"string","enum":["live","draft"],"description":"The status for the product, either `draft` or `live`. Default is `draft`.  For a product to appear in a catalog it must be in a `live` status."},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"type":"string","description":"The universal product code or european article number of the product."},"mpn":{"type":"string","description":"The manufacturer part number of the product."},"tags":{"type":"array","description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas. See [Product Tags](/docs/api/pxm/products/product-tags).","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}},"title":"product_attributes"},"relationships":{"description":"Relationships are established between different product entities.","type":"object","properties":{"variations":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}}}}}}}}},"title":"create_product_request"},"examples":{"create-product":{"summary":"Create a base product","value":{"data":{"type":"product","attributes":{"external_ref":"d0ddf10c-402c-4e0f-b421-94e7f682c603","name":"T-Shirt","sku":"97805","slug":"97805","description":"T-shirt.","status":"live","commodity_type":"physical","mpn":"1234-5678-TTTT","upc_ean":"12345656","tags":["tag1","tag2"],"custom_inputs":{"front":{"name":"T-Shirt Front","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false},"back":{"name":"T-Shirt Back","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false}},"locales":{"fr-FR":{"name":"T_Shirt","description":"T-Shirt."}}}}}},"build-rules":{"summary":"Create a base product, associate variations, configure build rules","value":{"data":{"type":"product","attributes":{"name":"Shirt","sku":"978055216732567","slug":"978055216732567","description":"T-shirt.","status":"live","commodity_type":"physical","mpn":"1234-5678-SSSS","upc_ean":"135623456","build_rules":{"default":"include","exclude":[["cbde9096-e0e1-43d8-a1aa-cb66cf1d299f","0b261f7d-753d-4af6-b9f4-62b436cca37d"]],"include":[["cf9e99f1-33dc-4991-88a1-3718678e9453","1592377e-ced8-452e-a025-e50272488b11"]]}},"relationships":{"variations":{"data":[{"type":"product-variation","id":"6c4b5caa-3819-4366-a14e-c5b85009544b"},{"type":"product-variation","id":"f192e114-9f8a-4284-99d0-4d9ccd8a0275"},{"type":"product-variation","id":"b1ae545e-3375-455f-b5ea-09669b60996f"}]}}}}},"sku-bundles":{"summary":"SKU-based bundles","value":{"data":{"type":"product","attributes":{"name":"Favourite games bundle","description":"All of your favourite DOOM games in one bundle","sku":"doom-franchise","mpn":"1234-5678-ABCD","upc_ean":"123456","commodity_type":"digital","components":{"games":{"name":"Game 1","max":1,"min":1,"sort_order":5,"options":[{"id":"7c0aa6df-0bd3-4d1f-b6f9-fd9358868869","type":"product","quantity":1,"default":true}]},"posters":{"name":"Game 2","max":1,"min":1,"sort_order":4,"options":[{"id":"f0ec8088-13e1-4a53-8b5d-3f4d973e05c9","type":"product","quantity":1,"default":false}]}}}}}},"sku-less-bundles":{"summary":"SKU-less bundles","value":{"data":{"type":"product","attributes":{"name":"Shower bundle","description":"A bundle of shower products","commodity_type":"physical","components":{"shampoo":{"name":"Shampoo","max":1,"min":1,"sort_order":1,"options":[{"id":"shampooProductID","type":"product","quantity":1,"default":true}]},"conditioner":{"name":"Conditioner","max":1,"min":1,"sort_order":2,"options":[{"id":"conditionerProductID","type":"product","quantity":1,"default":false}]}}}}}},"bundle-quantity-config":{"summary":"Create Bundle with Quantity Configuration","description":"Create a bundle where each selected option can have a configurable quantity. In this example, syrup is optional (0-2 types) with up to 3 pumps per syrup, and exactly one coffee type must be selected.","value":{"data":{"type":"product","attributes":{"name":"Coffee Bundle","description":"A customizable coffee bundle with optional syrups and coffee options","sku":"COFFEE-BUNDLE-001","commodity_type":"physical","status":"draft","components":{"syrup":{"name":"Syrup Selection","min":0,"max":2,"options":[{"id":"vanilla-id","type":"product","quantity":1,"min":1,"max":3,"default":true},{"id":"salted-caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"hazelnut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"toffee-nut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"pumpkin-spice-id","type":"product","quantity":1,"min":1,"max":3}]},"coffee":{"name":"Coffee Selection","min":1,"max":1,"options":[{"id":"cappuccino-id","type":"product","quantity":1,"default":true},{"id":"espresso-id","type":"product","quantity":1},{"id":"latte-id","type":"product","quantity":1}]}}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Creates a product with the following attributes.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included_response"}},"title":"single_product_response"},"examples":{"created-product":{"summary":"Create a base product","value":{"data":{"type":"product","id":"9c85b276-09b4-488e-a59c-c561bae14c9e","attributes":{"commodity_type":"physical","custom_inputs":{"back":{"name":"T-Shirt Back","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false},"front":{"name":"T-Shirt Front","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false}},"description":"T-shirt.","external_ref":"d0ddf10c-402c-4e0f-b421-94e7f682c603","locales":{"fr-FR":{"name":"T-Shirt","description":"T-Shirt."}},"mpn":"1234-5678-TTTT","name":"T-Shirt","sku":"97805","slug":"97805","status":"live","upc_ean":"12345656","tags":["tag1","tag2"]},"relationships":{"children":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/children"}},"component_products":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/variations"}}},"meta":{"created_at":"2022-08-18T14:25:57.391Z","owner":"store","product_types":["standard"],"updated_at":"2022-08-18T14:25:57.391Z"}}}},"build-rules":{"summary":"Create a base product, associate variations, configure build rules","value":{"data":{"type":"product","id":"9214719b-17fe-4ea7-896c-d61e60fc0d05","attributes":{"build_rules":{"default":"include","exclude":[["cbde9096-e0e1-43d8-a1aa-cb66cf1d299f","0b261f7d-753d-4af6-b9f4-62b436cca37d"]]},"commodity_type":"physical","description":"T-shirt.","locales":{"fr-FR":{"name":"shirt","description":"T-shirt."}},"mpn":"1234-5678-SSSS","name":"Shirt","sku":"978055216732567","slug":"978055216732567","status":"live","upc_ean":"135623456"},"relationships":{"children":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/children"}},"component_products":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/variations"}}},"meta":{"created_at":"2022-08-18T12:14:52.782Z","owner":"store","product_types":["standard"],"updated_at":"2022-08-18T12:14:52.782Z","variations":[{"id":"6c4b5caa-3819-4366-a14e-c5b85009544b","name":"Shirt Size","options":[{"id":"cbde9096-e0e1-43d8-a1aa-cb66cf1d299f","name":"Small","description":"Size Small"},{"id":"da9d88d0-8ea6-434c-a0dd-059caf595687","name":"Medium","description":"Size Medium"},{"id":"07493fea-74b0-40a2-972a-cd7e1d6561bd","name":"Large","description":"Size Large"}]},{"id":"b1ae545e-3375-455f-b5ea-09669b60996f","name":"Shirt Material","options":[{"id":"994c2029-519c-43d9-9c54-14f3af4e3efd","name":"Cotton","description":"Material Cotton"},{"id":"7951f3d9-f628-49f8-8a43-7749d28153d6","name":"Denim","description":"Material Denim"},{"id":"58115bff-589a-4287-98d8-373112102617","name":"Wool","description":"Material Wool"}]},{"id":"f192e114-9f8a-4284-99d0-4d9ccd8a0275","name":"Shirt Color","options":[{"id":"0b261f7d-753d-4af6-b9f4-62b436cca37d","name":"Red","description":"Color Red"},{"id":"55d6d785-cc52-453a-bff6-2cf9add8a580","name":"Green","description":"Color Green"},{"id":"a43d8b6f-b411-49aa-adaa-36a1a025051e","name":"Blue","description":"Color Blue"}]}]}}}},"bundle-quantity-config":{"summary":"Create Bundle with Quantity Configuration","description":"A bundle where each selected option can have a configurable quantity. In this example, syrup is optional (0-2 types) with up to 3 pumps per syrup, and exactly one coffee type must be selected.","value":{"data":{"type":"product","id":"143e9ded-b549-4631-831c-d27f5fb2fe2e","attributes":{"name":"Coffee Bundle","description":"A customizable coffee bundle with optional syrups and coffee options","sku":"COFFEE-BUNDLE-001","commodity_type":"physical","status":"live","components":{"syrup":{"name":"Syrup Selection","min":0,"max":2,"options":[{"id":"vanilla-id","type":"product","quantity":1,"min":1,"max":3,"default":true},{"id":"salted-caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"hazelnut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"toffee-nut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"pumpkin-spice-id","type":"product","quantity":1,"min":1,"max":3}]},"coffee":{"name":"Coffee Selection","min":1,"max":1,"options":[{"id":"cappuccino-id","type":"product","quantity":1,"default":true},{"id":"espresso-id","type":"product","quantity":1},{"id":"latte-id","type":"product","quantity":1}]}}},"relationships":{"children":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/children"}},"component_products":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/templates"}},"variations":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/variations"}}},"meta":{"created_at":"2024-04-14T10:34:00.000Z","owner":"organization","product_types":["bundle"],"updated_at":"2024-04-14T10:34:00.000Z","variation_matrix":{}}},"included":{"main_images":[],"files":[]}}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a variation option

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a variation option"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/variations/{variationID}/options"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a variation option

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `product-variation-option`.","type":"string","enum":["product-variation-option"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","description"],"properties":{"name":{"description":"A human recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string"},"sort_order":{"description":"By default, variations and variation options are sorted alphabetically. You can use the `sort_order` attribute to sort the order of your variation and variation options in the `variation_matrix`. \n \n The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want.  \n \n The variation option with the highest value of `sort_order` is displayed first. For example, a variation option with a `sort_order` value of `3` appears before a variation option with a `sort_order` value of `2`. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, and so on, zero or negative numbers. \n \n You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.\n \n You must rebuild your products for the sort order changes to take effect.\n","type":"integer"},"description":{"description":"A description of a product variation option.","type":"string"}}}}}},"title":"create_option"},"examples":{"create-variation-option":{"value":{"data":{"type":"product-variation-option","attributes":{"name":"Blue","sort_order":0,"description":"Our most popular color"}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully returns the created variation option.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"id":{"description":"A unique identifier that is generated when an option is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation-option`.","type":"string","enum":["product-variation-option"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string"},"description":{"description":"A human-recognizable description for the option.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"}}},"meta":{"type":"object","properties":{"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["organization","store"]},"created_at":{"type":"string","description":"The date and time an option is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time an option is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"}}}}}},"title":"created_option"},"examples":{"created-variation-option":{"value":{"data":{"type":"product-variation-option","id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","attributes":{"description":"Our most popular color","name":"Blue","sort_order":0},"meta":{"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}}}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a variation

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a variation"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/variations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a variation

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `product-variation`.","type":"string","enum":["product-variation"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The variation name.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. \n \n The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. \n \n You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.\n \n You must rebuild your products for the sort order changes to take effect.\n","type":"integer"}}}}}},"title":"create_variation"},"examples":{"create-variation":{"summary":"Create a variation","value":{"data":{"type":"product-variation","attributes":{"name":"Paint Color","sort_order":10}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Returns a created variation with the following attributes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a variation is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation`.","type":"string","enum":["product-variation"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A human-recognizable identifier for a variation.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"}}},"meta":{"type":"object","properties":{"owner":{"description":"The owner of the resource, either `organization` or `store`.","type":"string","enum":["organization","store"]},"created_at":{"type":"string","description":"The date and time a variation is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a variation is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"}}}}}},"title":"created_variation"},"examples":{"created-variation":{"value":{"data":{"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"product-variation","attributes":{"name":"Paint Color","sort_order":10},"meta":{"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}}}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a custom relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a custom relationship"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/custom-relationships/{customRelationshipSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the specified custom relationship.

Custom Relationships cannot be deleted if they are in use.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"customRelationshipSlug","in":"path","schema":{"type":"string","example":"CRP_electric_devices_2024"},"required":true,"description":"A custom relationship slug."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a hierarchy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a hierarchy"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/hierarchies/{hierarchyID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the specified hierarchy and all its children.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a modifier(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a modifier"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/variations/{variationID}/options/{optionID}/modifiers/{modifierID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You cannot delete a modifier if it is in use. Deleting a modifier in us returns a `422 Failed Validation` error.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"optionID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the option."},{"name":"modifierID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the modifier."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a node's parent

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a node's parent"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}/relationships/parent"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a node's parent

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Deletes a node's product relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Deletes a node's product relationships"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}/relationships/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a node's product relationships

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier of the product to be attached to the node.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]}}}}},"title":"node_products"},"examples":{"delete-node-product-relationships":{"value":{"data":[{"type":"product","id":"9c85b276-09b4-488e-a59c-c561bae14c9e"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the updated node","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"title":"single_node"},"examples":{"created-node-product-relationships":{"value":{"data":{"type":"node","id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"admin_attributes":{"cost_of_goods":"42.0"},"shopper_attributes":{"charge_type":"credit card"},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}}}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Deletes a node

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Deletes a node"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a node by the node ID

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a product file relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a product file relationships"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/products/{productID}/relationships/files"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a product file relationships

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a file generated when a file is created.","type":"string"},"type":{"description":"This represents the type of resource being returned. Always `file`.","type":"string","enum":["file"]},"meta":{"type":"object","properties":{"tags":{"description":"The files associated with a product.","type":"array","items":{"type":"string"}}},"additionalProperties":false}}}}},"title":"product_files_request"},"examples":{"delete-product-file-relationships":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"file"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"file"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete Main Image Relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Main Image Relationships"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/products/{productID}/relationships/main_image"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete Main Image Relationships

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a product template relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a product template relationship"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/products/{productID}/relationships/templates"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a product template relationship

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of a template."},"type":{"type":"string","enum":["template"],"description":"This represents the type of resource object being returned. Always `template`."}}}}},"title":"product_templates_request"},"examples":{"delete-product-template-relationship":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"template"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"template"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a product variation relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a product variation relationships"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/products/{productID}/relationships/variations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a product variation relationships

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the product variation."},"type":{"type":"string","enum":["product-variation"],"description":"This represents the type of resource being returned. Always `product-variation`."}}}}},"title":"product_variations_request"},"examples":{"delete-product-variation-relationships":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"product-variation"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a product"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/products/{productID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes the specified product.

You cannot delete a product if it is part of a bundle. You must first delete the bundle before you delete the product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Deletes the specified product."},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a variation option

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a variation option"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/variations/{variationID}/options/{optionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a variation option

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"optionID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the option."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a variation and all it's associated options.

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a variation and all it's associated options."}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/variations/{variationID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a variation and all it's associated options.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete Custom Relationships from a Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Custom Relationships from a Product"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/products/{productID}/custom-relationships"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete Custom Relationships from a Product. Multiple Custom Relationships can be deleted from a product in one request.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","type"],"properties":{"slug":{"type":"string","description":"The slug of the custom relationship."},"type":{"type":"string","enum":["custom-relationship"],"description":"This represents the type of resource. Always `custom-relationship`."}}}}},"title":"attach_custom_relationship_request"},"examples":{"assign-custom-relationship-to-product":{"value":{"data":[{"type":"custom-relationship","slug":"CRP_related_products"},{"type":"custom-relationship","slug":"CRP_cart_products"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Successfully deleted custom relationships."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Detach multiple nodes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Detach multiple nodes"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/detach_nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Dissociates products from multiple hierarchies and their children nodes. You can apply filters to search for the appropriate products to detach. For general filtering syntax, see [**Filtering**](/guides/Getting-Started/filtering).
 
The following attributes and operators are supported.
 
 | Operator                  | Attribute                                                                                                                                               | Description                                                                                                                                                                                                                                             | Example                                          |
 | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------- |
 | `eq`                      | `id`, `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `name`, `templates`, `commodity_type`, `owner`, `product_types`, `parent_id`, `component_option_id`, `tags`, `status`, `has_nodes (false only)`, `created_at`, `updated_at`, `external_ref`, `description` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. For `product_types`, you can only specify one product type. **Note:** `has_nodes` can only be filtered as `false`. **Note:** `component_option_id` matches when a bundle includes that product id as a component option. | `?filter=eq(name,some-name)` |
 | `like`                    | `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `name`, `tags`, `description`, `external_ref`                                                        | Like. Checks if the operand contains the specified string. Wildcards are supported.                                                                                                                                                                     | `?filter=like(name,*some-name*)`                 |
 | `in`                      | `id`, `name`, `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `product_types`, `parent_id`, `component_option_id`, `tags`, `external_ref`                                   | Checks if the values are included in the specified list. If they are, the condition is true. For `product_types`, you can specify more than one product type.                                                                                           | `?filter=in(id,some-id)`                         |
 | `gt`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Greater than. Checks if the value of the field is greater than the given value.                                                                                                                                                                         | `?filter=gt(updated_at,2024-01-01T00:00:00Z)`    |
 | `ge`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Greater than or equal to. Checks if the value of the field is greater than or equal to the given value.                                                                                                                                                 | `?filter=ge(created_at,2023-01-01T00:00:00Z)`    |
 | `lt`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Less than. Checks if the value of the field is less than the given value.                                                                                                                                                                               | `?filter=lt(updated_at,2025-01-01T00:00:00Z)`    |
 | `le`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Less than or equal to. Checks if the value of the field is less than or equal to the given value.                                                                                                                                                       | `?filter=le(created_at,2022-01-01T00:00:00Z)`    |
 | `eq` (extensions)         | `extensions.book.isbn`                                                                                                                                  | Filters using a nested extension field.                                                                                                                                                                                                                 | `?filter=eq(extensions.book.isbn,1765426)`       |
 | `eq` (shopper_attributes) | `shopper_attributes.color`                                                                                                                              | Filters using a shopper custom attribute field.                                                                                                                                                                                                         | `?filter=eq(shopper_attributes.color,red)`       |
 | `eq` (admin_attributes)   | `admin_attributes.warehouse`                                                                                                                            | Filters using an admin custom attribute field.                                                                                                                                                                                                          | `?filter=eq(admin_attributes.warehouse,US-EAST)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["filter","node_ids"],"properties":{"filter":{"type":"string","description":"You can apply filters to search for the appropriate products to detach. See [Detach multiple nodes](/docs/api/pxm/products/detach-nodes).\n","example":"eq(sku,book)"},"node_ids":{"type":"array","description":"A list of node unique identifiers that you want to assign to the products.","example":["123"],"items":{"type":"string"}}}}}},"examples":{"product-attach-nodes":{"summary":"Attach multiple nodes","value":{"data":{"filter":"eq(sku,book)","node_ids":["123"]}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The request dissociates the products that you have selected from multiple hierarchies and their children and returns the following.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"nodes_detached":{"description":"Number of nodes dissociated from the products.","type":"integer"},"nodes_not_found":{"type":"array","description":"A list of node unique identifiers that could not be identified.","example":["123"],"items":{"type":"string"}}}}}},"examples":{"created-product":{"summary":"Detach multiple nodes","value":{"meta":{"nodes_detached":1,"nodes_not_found":[]}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a Relationship between a product with one or more products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a Relationship between a product with one or more products"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/pcm/products/{productID}/custom-relationships/{customRelationshipSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a Relationship between a product with one or more products

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."},{"name":"customRelationshipSlug","in":"path","schema":{"type":"string","example":"CRP_electric_devices_2024"},"required":true,"description":"A custom relationship slug."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The ID of the product you want to relate."},"type":{"type":"string","enum":["product"],"description":"This represents the type of resource being returned. Always `product`."}}}}},"title":"product_association_delete_request"},"examples":{"delete-product-association":{"value":{"data":[{"type":"product","id":"68c48149-0e94-4ef2-93d5-8d5f3774980a"},{"type":"product","id":"ab4826d1-4a5a-4951-a2a5-98058899f891"},{"type":"product","id":"97b7fac2-91dd-4755-81b0-bdffe8e7eabd"},{"type":"product","id":"a0ef3291-2ec1-4d7d-9d6d-1705ae01bb99"},{"type":"product","id":"bde79675-4783-40b7-8a7e-ac6df41459c6"},{"type":"product","id":"aaddd5f4-a5f8-42e8-be9a-097986f22e58"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Products are dissociated."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Duplicate a hierarchy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Duplicate a hierarchy"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/hierarchies/{hierarchyID}/duplicate_job"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Using this option, you can duplicate an existing hierarchy. This is useful because it enables you to quickly and easily create multiple hierarchies with the same node structure.

When you duplicate a hierarchy, you can specify a new name and/or a new description and/or a new slug for the duplicated hierarchy. All other attributes will stay the same.

Any nodes in the existing hierarchy are also replicated in the duplicated hierarchy. In addition, you can optionally use the `include_products` attribute to specify whether you want products associated with the nodes in an existing hierarchy to be associated with the nodes in the duplicated hierarchy. By default, product relationships in an existing hierarchy are not duplicated in a duplicate hierarchy.

Duplicating a hierarchy is an asynchronous operation. When you duplicate a hierarchy, a job is created. The jobId of the job is displayed in the response. When the job is complete, the duplicate hierarchy operation is also complete. You can use the jobId to see the status of your job using Get a Job.

Jobs are processed one at a time. You can continue to send duplicate hierarchy requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. 

Once the job is complete, run:

- Get all hierarchies to retrieve the HierarchyId of your duplicated hierarchy.
- Get a hierarchy to retrieve the nodes and (if applicable) products associated with the duplicated hierarchy.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The name of the duplicate hierarchy. The maximum length is 1000 characters.","type":"string"},"description":{"description":"A description of the duplicate hierarchy.","type":"string"},"slug":{"description":"The slug of the duplicate hierarchy. Must be lower case and use dashes instead of spaces.","type":"string"},"include_products":{"description":"Specify `true` if you want the product relationships in the existing nodes associated in your duplicated hierarchy. If not, specify `false`.","type":"boolean"}}}}}},"title":"duplicate_job"},"examples":{"duplicate-hierarchy":{"value":{"data":{"type":"hierarchy","attributes":{"name":"New Shoes","description":"New Shoes Category","include_products":true}}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Successfully returns the duplicate hierarchy job ID","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a job is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `pim-job`.","type":"string","enum":["pim-job"]},"attributes":{"type":"object","required":["started_at","completed_at","created_at","updated_at","type","status"],"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true},"completed_at":{"type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true,"description":"The date and time a job is completed."},"created_at":{"type":"string","description":"The date and time a job is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a job is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"type":{"type":"string","description":"The status of a job.\n\n* `pending` - Commerce has received the request but is currently busy processing other requests.\n* `started` - Commerce has started processing the job.\n* `success` - The job has successfully completed.\n* `failed` - The job has failed.\n","enum":["child-products","product-import","product-export","hierarchy-duplicate","pricebook-import","pricebook-delete","hierarchy-delete","indexing-job","attach-nodes"]},"status":{"type":"string","enum":["pending","cancelled","cancelling","started","success","failed"]}}},"meta":{"type":"object","required":["x_request_id"],"properties":{"x_request_id":{"type":"string","description":"Applies to all job types. A unique request ID is generated when a job is created."},"copied_from":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated."},"hierarchy_id":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID."},"file_locations":{"type":"array","nullable":true,"description":"If the job type is `product_export`, a link to the file is created when running a job.","items":{"type":"string"}},"filter":{"type":"string","nullable":true,"description":"The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export."}}}},"title":"job"}},"title":"single"},"examples":{"duplicated-hierarchy":{"value":{"data":{"type":"pim-job","id":"1d9b101e-a40a-4e53-9f54-08a9ede65019","attributes":{"completed_at":null,"created_at":"2024-01-11T22:49:10.338Z","started_at":null,"status":"pending","type":"hierarchy-duplicate","updated_at":"2024-01-11T22:49:10.338Z"},"meta":{"x_request_id":"40995a1d-c0c1-4d52-a178-bfb5399ab0ec"}}}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Export Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Export Products"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/export"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The Export API is available to make bulk updates to products in Product Experience Manager. You might also export products for your personal requirements. 
 
The Export API builds a CSV file containing the product entries. A CSV file can contain up to 50,000 product entries. If you have more than 50,000 product entries, then another CSV file is created and so on, until all your products are exported.

The Job endpoint response specifies the location where the CSV file is stored. See [Characteristics of CSV Files](/docs/api/pxm/products/product-export#characteristics-of-exporting-products).

### Custom Attributes in Exported CSV

Exported CSV files include custom attribute columns using the prefixes `shopper_attributes.` and `admin_attributes.` followed by the attribute key name. For example, a product with `admin_attributes: {cost_of_goods: "42.0"}` produces a column `admin_attributes.cost_of_goods` in the exported file.

You can select specific attribute columns to include in the export using the `columns.include` parameter. You may specify individual keys (for example, `admin_attributes.cost_of_goods`) or use a wildcard to include all keys of a given type (for example, `admin_attributes.*`). You cannot combine a wildcard and individual keys for the same attribute type in a single export request.

### Exporting Selected Columns
Product exports support the ability to select a subset of columns to be included in the generated .csv file. This allows you to export only the data you need, making it easier to work with smaller, more focused datasets.

 To specify the columns you want to include in the export, use the columns.include parameter in the request body of this endpoint. This parameter accepts an array of strings, where each string represents the name of a product attribute or a flow field.

 #### Specifying Flow Field Columns:
 
 The format for specifying flow field columns depends on the useTemplateSlugs setting:
 
 * useTemplateSlugs: `true`: Specify flow field columns using the format: `products(<flow_slug>):<field_name>`. For example: `products(my_flow):my_field`.
 * useTemplateSlugs: `false` (default): Specify flow field columns using the format: `template:<flow_id>:<field_name>`. For example: `template:82c10a02-1851-4992-8ecb-d44f2782d09b:my_field`.
 
 #### Mandatory Fields:

 To ensure successful re-importing of product data, the following fields are always included in the export, regardless of the columns.include parameter:
   
   * id
   * name
   * sku
   * external_ref
   * commodity_type
 
 If the `columns.include` parameter is not provided in the request, the system will export all available product fields.
 
 ### Filtering
 
The following attributes and operators are supported.

| Operator                  | Attribute                                                                                                                                               | Description                                                                                                                                                                                                                                             | Example                                          |
 | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------- |
 | `eq`                      | `id`, `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `name`, `templates`, `commodity_type`, `owner`, `product_types`, `parent_id`, `component_option_id`, `tags`, `status`, `has_nodes (false only)`, `created_at`, `updated_at`, `external_ref`, `description` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. For `product_types`, you can only specify one product type. **Note:** `has_nodes` can only be filtered as `false`. **Note:** `component_option_id` matches when a bundle includes that product id as a component option. | `?filter=eq(name,some-name)` |
 | `like`                    | `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `name`, `tags`, `description`, `external_ref`                                                        | Like. Checks if the operand contains the specified string. Wildcards are supported.                                                                                                                                                                     | `?filter=like(name,*some-name*)`                 |
 | `in`                      | `id`, `name`, `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `product_types`, `parent_id`, `component_option_id`, `tags`, `external_ref`                                   | Checks if the values are included in the specified list. If they are, the condition is true. For `product_types`, you can specify more than one product type.                                                                                           | `?filter=in(id,some-id)`                         |
 | `gt`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Greater than. Checks if the value of the field is greater than the given value.                                                                                                                                                                         | `?filter=gt(updated_at,2024-01-01T00:00:00Z)`    |
 | `ge`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Greater than or equal to. Checks if the value of the field is greater than or equal to the given value.                                                                                                                                                 | `?filter=ge(created_at,2023-01-01T00:00:00Z)`    |
 | `lt`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Less than. Checks if the value of the field is less than the given value.                                                                                                                                                                               | `?filter=lt(updated_at,2025-01-01T00:00:00Z)`    |
 | `le`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Less than or equal to. Checks if the value of the field is less than or equal to the given value.                                                                                                                                                       | `?filter=le(created_at,2022-01-01T00:00:00Z)`    |
 | `eq` (extensions)         | `extensions.book.isbn`                                                                                                                                  | Filters using a nested extension field.                                                                                                                                                                                                                 | `?filter=eq(extensions.book.isbn,1765426)`       |
 | `eq` (shopper_attributes) | `shopper_attributes.color`                                                                                                                              | Filters using a shopper custom attribute field.                                                                                                                                                                                                         | `?filter=eq(shopper_attributes.color,red)`       |
 | `eq` (admin_attributes)   | `admin_attributes.warehouse`                                                                                                                            | Filters using an admin custom attribute field.                                                                                                                                                                                                          | `?filter=eq(admin_attributes.warehouse,US-EAST)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"useTemplateSlugs","description":"Set to `true` if you want to use a template slug instead of a template ID when exporting products that have custom data.","in":"query","style":"form","explode":true,"schema":{"type":"boolean","default":false}},{"name":"filter","in":"query","description":"\nMany Commerce API endpoints support filtering. The general syntax is described [**here**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n\nFor more information about the attributes and operators that this endpoint supports, see [Export Products](/docs/api/pxm/products/export-products).\n","style":"form","explode":true,"schema":{"type":"string"},"examples":{"eq":{"value":"eq(name,some-name)"},"like":{"value":"like(name,*some-name*)"},"in":{"value":"in(id,some-id)"}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","required":["type"],"properties":{"attributes":{"type":"object","properties":{"columns":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"}}}}}},"type":{"type":"string","example":"product-export"}}}}},"examples":{"product-export-columns":{"summary":"Export only a subset of columns when useTemplateSlugs is `false`","value":{"data":{"type":"product-export","attributes":{"columns":{"include":["description","template:a1b2c3d4-e5f6-7890-1234-567890abcdef:isbn"]}}}}},"product-export-columns-template-slugs":{"summary":"Export only a subset of columns when useTemplateSlugs is `true`","value":{"data":{"type":"product-export","attributes":{"columns":{"include":["description","products(book):isbn"]}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Export started","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a job is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `pim-job`.","type":"string","enum":["pim-job"]},"attributes":{"type":"object","required":["started_at","completed_at","created_at","updated_at","type","status"],"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true},"completed_at":{"type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true,"description":"The date and time a job is completed."},"created_at":{"type":"string","description":"The date and time a job is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a job is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"type":{"type":"string","description":"The status of a job.\n\n* `pending` - Commerce has received the request but is currently busy processing other requests.\n* `started` - Commerce has started processing the job.\n* `success` - The job has successfully completed.\n* `failed` - The job has failed.\n","enum":["child-products","product-import","product-export","hierarchy-duplicate","pricebook-import","pricebook-delete","hierarchy-delete","indexing-job","attach-nodes"]},"status":{"type":"string","enum":["pending","cancelled","cancelling","started","success","failed"]}}},"meta":{"type":"object","required":["x_request_id"],"properties":{"x_request_id":{"type":"string","description":"Applies to all job types. A unique request ID is generated when a job is created."},"copied_from":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated."},"hierarchy_id":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID."},"file_locations":{"type":"array","nullable":true,"description":"If the job type is `product_export`, a link to the file is created when running a job.","items":{"type":"string"}},"filter":{"type":"string","nullable":true,"description":"The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export."}}}},"title":"job"}},"title":"single"},"examples":{"pending":{"summary":"Successful Job","value":{"data":{"type":"pim-job","id":"7e1b9ba1-c844-4556-9b16-4ae3f0988b0f","attributes":{"completed_at":null,"created_at":"2024-01-05T15:27:23.161Z","started_at":null,"status":"pending","type":"product-export","updated_at":"2024-01-05T15:27:23.161Z"},"meta":{"file_locations":null,"filter":"eq(sku,product-1)","x_request_id":"fad8c5c0-9546-4e0c-b68e-8a2d809891e5"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Extending Products with Templates

```mdx-code-block
import TemplatesOverview from '/docs/partials/pxm/templates/extendingproducts.mdx';

<TemplatesOverview />
```

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Get a hierarchy's children(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a hierarchy's children"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/hierarchies/{hierarchyID}/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a hierarchy's children

#### Filtering

Many Commerce API endpoints support filtering. The general syntax is described in [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator        | Attribute                                                                                 | Description                                                                                      | Example                                  |
|----------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|------------------------------------------|
| `eq`           | `id`, `hierarchy_id`, `owner`, `parent_id`, `name`, `slug`, `description`, `has_children`, `created_at`, `updated_at`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.id`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Equals. Checks if the value of the attribute matches the specified value. | `filter=eq(name,some-name)`, `filter=eq(locales.fr-FR.name,Nom-du-produit)` |
| `in`           | `id`, `hierarchy_id`,  `parent_id`, `breadcrumbs.id`                                              | Checks if the value of the attribute is included in the specified list.                        | `filter=in(id,1,2,3,4)`                 |
| `lt`, `le`, `gt`, `ge` | `id`, `hierarchy_id`,  `parent_id`, `created_at`, `updated_at`         | Comparison operators. `lt`: Less than, `le`: Less than or equal to, `gt`: Greater than, `ge`: Greater than or equal to. | `filter=lt(id,100)`, `filter=ge(created_at,2022-01-01)` |
| `like`         | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Like. Checks if the attribute contains the specified string (wildcards supported).            | `filter=like(name,*some-name*)`, `filter=like(locales.es-ES.description,*descripción*)` |
| `ilike`        | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Case-insensitive like. Same as `like` but ignores case when matching. | `filter=ilike(name,*some-name*)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"filter","in":"query","description":"Many Commerce API endpoints support filtering. The general syntax is described [**here**](/guides/Getting-Started/filtering).\n","style":"form","explode":true,"schema":{"type":"string"},"examples":{"eq":{"value":"eq(name,some-name)"},"like":{"value":"like(name,*some-name*)"},"in":{"value":"in(id,some-id)"},"lt":{"value":"lt(id,100)"},"le":{"value":"le(created_at,2023-01-01)"},"gt":{"value":"gt(updated_at,2023-01-01)"},"ge":{"value":"ge(parent_id,500)"},"eq-owner":{"value":"eq(owner,store)"},"eq-locale":{"value":"eq(locales.fr-FR.name,Nom-du-produit)"},"like-locale":{"value":"like(locales.es-ES.description,*descripción*)"}}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns the hierarchy's children.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"description":"An array of nodes.","type":"array","items":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"}},"title":"multi_nodes"},"examples":{"get-hierarchy-children":{"value":{"data":[{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","type":"node","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}},{"type":"node","id":"b2f5e53e-de3c-4548-98da-120f8b185d34","attributes":{"description":"All Dress Shoes","locales":{"fr-FR":{"name":"Chaussures habillées","description":"Toutes les chaussures habillées"}},"name":"Dress Shoes","slug":"dress-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/products"}}},"meta":{"created_at":"2024-01-11T19:50:21.729Z","owner":"store","sort_order":3,"updated_at":"2024-01-11T19:50:21.729Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"b2f5e53e-de3c-4548-98da-120f8b185d34","name":"Dress Shoes","slug":"dress-shoes","locales":{"fr-FR":{"name":"Node 2 in French"}}}]}}],"meta":{"results":{"total":2}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get All Jobs(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get All Jobs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The jobs endpoints displays the status of a number of endpoints that function as jobs, for example, product import and export, price book import, building child products, and duplicating hierarchies.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all the jobs.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"data":{"description":"An array of jobs.","type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a job is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `pim-job`.","type":"string","enum":["pim-job"]},"attributes":{"type":"object","required":["started_at","completed_at","created_at","updated_at","type","status"],"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true},"completed_at":{"type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true,"description":"The date and time a job is completed."},"created_at":{"type":"string","description":"The date and time a job is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a job is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"type":{"type":"string","description":"The status of a job.\n\n* `pending` - Commerce has received the request but is currently busy processing other requests.\n* `started` - Commerce has started processing the job.\n* `success` - The job has successfully completed.\n* `failed` - The job has failed.\n","enum":["child-products","product-import","product-export","hierarchy-duplicate","pricebook-import","pricebook-delete","hierarchy-delete","indexing-job","attach-nodes"]},"status":{"type":"string","enum":["pending","cancelled","cancelling","started","success","failed"]}}},"meta":{"type":"object","required":["x_request_id"],"properties":{"x_request_id":{"type":"string","description":"Applies to all job types. A unique request ID is generated when a job is created."},"copied_from":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated."},"hierarchy_id":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID."},"file_locations":{"type":"array","nullable":true,"description":"If the job type is `product_export`, a link to the file is created when running a job.","items":{"type":"string"}},"filter":{"type":"string","nullable":true,"description":"The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export."}}}},"title":"job"}},"meta":{"type":"object","required":["results"],"properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","required":["total"],"properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}},"title":"multi"},"examples":{"completed":{"summary":"Get all jobs","value":{"data":[{"type":"pim-job","id":"1ea62172-57f6-45e5-a708-ab5bd634e3f9","attributes":{"completed_at":"2024-01-05T13:46:42.142Z","created_at":"2024-01-05T13:46:41.695Z","started_at":"2024-01-05T13:46:42.07Z","status":"success","type":"product-import","updated_at":"2024-01-05T13:46:42.07Z"},"meta":{"x_request_id":"7e832a26-d615-4305-b26a-e33c9c2fc06a"}},{"type":"pim-job","id":"3ab3deca-1f11-47b7-a409-24ea3234d72c","attributes":{"completed_at":null,"created_at":"2024-01-05T15:27:23.161Z","started_at":"2024-01-05T15:27:23.65Z","updated_at":"2024-01-05T15:27:23.65Z","status":"started","type":"product-import"},"meta":{"x_request_id":"9ac00140-0037-4c6a-913c-b812196a2de6"}},{"type":"pim-job","id":"7e1b9ba1-c844-4556-9b16-4ae3f0988b0f","attributes":{"completed_at":"2024-01-05T15:27:23.663Z","created_at":"2024-01-05T15:27:23.161Z","started_at":"2024-01-05T15:27:23.65Z","updated_at":"2024-01-05T15:27:23.65Z","status":"success","type":"product-export"},"meta":{"file_locations":[],"filter":"eq(sku,product-1)","x_request_id":"fad8c5c0-9546-4e0c-b68e-8a2d809891e5"}}],"meta":{"results":{"total":1}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all modifiers

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all modifiers"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/variations/{variationID}/options/{optionID}/modifiers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all modifiers

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"optionID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the option."},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns all variation modifiers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a modifier that is generated automatically when a modifier is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation-modifier`.","type":"string","enum":["product-variation-modifier"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"type":{"description":"You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n","type":"string","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"description":"Required for non-builder modifiers. The value of the modifier type.","type":"string"},"seek":{"description":"Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.","type":"string"},"set":{"description":"Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.","type":"string"},"reference_name":{"description":"The name of the modifier.","type":"string"}}},"meta":{"type":"object","properties":{"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]}}}}}},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","properties":{"results":{"type":"object","description":"Contains the results for the entire collection.","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":3}}}}}},"title":"multi_modifiers"},"examples":{"list-variations":{"value":{"data":[{"type":"product-variation-modifier","id":"68ec4892-9e4c-4154-a9fd-f5a9fb1f6878","attributes":{"type":"sku_equals","value":"newSku"},"meta":{"owner":"store"}},{"type":"product-variation-modifier","id":"a510cddc-e946-4c22-9541-54626a7cf0ec","attributes":{"seek":"{color}","set":"red","type":"slug_builder"},"meta":{"owner":"store"}},{"type":"product-variation-modifier","id":"2f0cbb06-8880-4a75-bfc6-a20f0f73a997","attributes":{"reference_name":"PriceEqual","type":"price"},"meta":{"owner":"store"}}],"meta":{"results":{"total":3}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a node's children(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a node's children"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the child nodes for a specified node.

#### Filtering

Many Commerce API endpoints support filtering. The general syntax is described in [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator        | Attribute                                                                                 | Description                                                                                      | Example                                  |
|----------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|------------------------------------------|
| `eq`           | `id`, `hierarchy_id`, `owner`, `parent_id`, `name`, `slug`, `description`, `has_children`, `created_at`, `updated_at`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.id`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Equals. Checks if the value of the attribute matches the specified value. | `filter=eq(name,some-name)`, `filter=eq(locales.fr-FR.name,Nom-du-produit)` |
| `in`           | `id`, `hierarchy_id`,  `parent_id`, `breadcrumbs.id`                                              | Checks if the value of the attribute is included in the specified list.                        | `filter=in(id,1,2,3,4)`                 |
| `lt`, `le`, `gt`, `ge` | `id`, `hierarchy_id`,  `parent_id`, `created_at`, `updated_at`         | Comparison operators. `lt`: Less than, `le`: Less than or equal to, `gt`: Greater than, `ge`: Greater than or equal to. | `filter=lt(id,100)`, `filter=ge(created_at,2022-01-01)` |
| `like`         | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Like. Checks if the attribute contains the specified string (wildcards supported).            | `filter=like(name,*some-name*)`, `filter=like(locales.es-ES.description,*descripción*)` |
| `ilike`        | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Case-insensitive like. Same as `like` but ignores case when matching. | `filter=ilike(name,*some-name*)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"filter","in":"query","description":"Many Commerce API endpoints support filtering. The general syntax is described [**here**](/guides/Getting-Started/filtering).\n","style":"form","explode":true,"schema":{"type":"string"},"examples":{"eq":{"value":"eq(name,some-name)"},"like":{"value":"like(name,*some-name*)"},"in":{"value":"in(id,some-id)"},"lt":{"value":"lt(id,100)"},"le":{"value":"le(created_at,2023-01-01)"},"gt":{"value":"gt(updated_at,2023-01-01)"},"ge":{"value":"ge(parent_id,500)"},"eq-owner":{"value":"eq(owner,store)"},"eq-locale":{"value":"eq(locales.fr-FR.name,Nom-du-produit)"},"like-locale":{"value":"like(locales.es-ES.description,*descripción*)"}}},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the node's children","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"description":"An array of nodes.","type":"array","items":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"}},"title":"multi_nodes"},"examples":{"get-node-children":{"value":{"data":[{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","type":"node","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}},{"type":"node","id":"b2f5e53e-de3c-4548-98da-120f8b185d34","attributes":{"description":"All Dress Shoes","locales":{"fr-FR":{"name":"Chaussures habillées","description":"Toutes les chaussures habillées"}},"name":"Dress Shoes","slug":"dress-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/products"}}},"meta":{"created_at":"2024-01-11T19:50:21.729Z","owner":"store","sort_order":3,"updated_at":"2024-01-11T19:50:21.729Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"b2f5e53e-de3c-4548-98da-120f8b185d34","name":"Dress Shoes","slug":"dress-shoes","locales":{"fr-FR":{"name":"Node 2 in French"}}}]}}],"meta":{"results":{"total":2}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all nodes in a hierarchy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all nodes in a hierarchy"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A fully paginated view of all nodes in a hierarchy regardless of depth.

#### Filtering

Many Commerce API endpoints support filtering. The general syntax is described in [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator        | Attribute                                                                                 | Description                                                                                      | Example                                  |
|----------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|------------------------------------------|
| `eq`           | `id`, `hierarchy_id`, `owner`, `parent_id`, `name`, `slug`, `description`, `has_children`, `created_at`, `updated_at`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.id`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Equals. Checks if the value of the attribute matches the specified value. | `filter=eq(name,some-name)`, `filter=eq(locales.fr-FR.name,Nom-du-produit)` |
| `in`           | `id`, `hierarchy_id`,  `parent_id`, `breadcrumbs.id`                                              | Checks if the value of the attribute is included in the specified list.                        | `filter=in(id,1,2,3,4)`                 |
| `lt`, `le`, `gt`, `ge` | `id`, `hierarchy_id`,  `parent_id`, `created_at`, `updated_at`         | Comparison operators. `lt`: Less than, `le`: Less than or equal to, `gt`: Greater than, `ge`: Greater than or equal to. | `filter=lt(id,100)`, `filter=ge(created_at,2022-01-01)` |
| `like`         | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Like. Checks if the attribute contains the specified string (wildcards supported).            | `filter=like(name,*some-name*)`, `filter=like(locales.es-ES.description,*descripción*)` |
| `ilike`        | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Case-insensitive like. Same as `like` but ignores case when matching. | `filter=ilike(name,*some-name*)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"filter","in":"query","description":"Many Commerce API endpoints support filtering. The general syntax is described [**here**](/guides/Getting-Started/filtering).\n","style":"form","explode":true,"schema":{"type":"string"},"examples":{"eq":{"value":"eq(name,some-name)"},"like":{"value":"like(name,*some-name*)"},"in":{"value":"in(id,some-id)"},"lt":{"value":"lt(id,100)"},"le":{"value":"le(created_at,2023-01-01)"},"gt":{"value":"gt(updated_at,2023-01-01)"},"ge":{"value":"ge(parent_id,500)"},"eq-owner":{"value":"eq(owner,store)"},"eq-locale":{"value":"eq(locales.fr-FR.name,Nom-du-produit)"},"like-locale":{"value":"like(locales.es-ES.description,*descripción*)"}}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the node's children","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"description":"An array of nodes.","type":"array","items":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"}},"title":"multi_nodes"},"examples":{"get-all-nodes":{"value":{"data":[{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","type":"node","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}},{"type":"node","id":"b2f5e53e-de3c-4548-98da-120f8b185d34","attributes":{"description":"All Dress Shoes","locales":{"fr-FR":{"name":"Chaussures habillées","description":"Toutes les chaussures habillées"}},"name":"Dress Shoes","slug":"dress-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/products"}}},"meta":{"created_at":"2024-01-11T19:50:21.729Z","owner":"store","sort_order":3,"updated_at":"2024-01-11T19:50:21.729Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"b2f5e53e-de3c-4548-98da-120f8b185d34","name":"Dress Shoes","slug":"dress-shoes","locales":{"fr-FR":{"name":"Node 2 in French"}}}]}}],"meta":{"results":{"total":2}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## List all nodes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List all nodes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/hierarchies/nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A fully paginated view of all nodes in all hierarchies regardless of depth.

#### Filtering

Many Commerce API endpoints support filtering. The general syntax is described in [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator        | Attribute                                                                                 | Description                                                                                      | Example                                  |
|----------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|------------------------------------------|
| `eq`           | `id`, `hierarchy_id`, `owner`, `parent_id`, `name`, `slug`, `description`, `has_children`, `created_at`, `updated_at`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.id`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Equals. Checks if the value of the attribute matches the specified value. | `filter=eq(name,some-name)`, `filter=eq(locales.fr-FR.name,Nom-du-produit)` |
| `in`           | `id`, `hierarchy_id`,  `parent_id`, `breadcrumbs.id`                                              | Checks if the value of the attribute is included in the specified list.                        | `filter=in(id,1,2,3,4)`                 |
| `lt`, `le`, `gt`, `ge` | `id`, `hierarchy_id`,  `parent_id`, `created_at`, `updated_at`         | Comparison operators. `lt`: Less than, `le`: Less than or equal to, `gt`: Greater than, `ge`: Greater than or equal to. | `filter=lt(id,100)`, `filter=ge(created_at,2022-01-01)` |
| `like`         | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Like. Checks if the attribute contains the specified string (wildcards supported).            | `filter=like(name,*some-name*)`, `filter=like(locales.es-ES.description,*descripción*)` |
| `ilike`        | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Case-insensitive like. Same as `like` but ignores case when matching. | `filter=ilike(name,*some-name*)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"filter","in":"query","description":"Many Commerce API endpoints support filtering. The general syntax is described [**here**](/guides/Getting-Started/filtering).\n","style":"form","explode":true,"schema":{"type":"string"},"examples":{"eq":{"value":"eq(name,some-name)"},"like":{"value":"like(name,*some-name*)"},"in":{"value":"in(id,some-id)"},"lt":{"value":"lt(id,100)"},"le":{"value":"le(created_at,2023-01-01)"},"gt":{"value":"gt(updated_at,2023-01-01)"},"ge":{"value":"ge(parent_id,500)"},"eq-owner":{"value":"eq(owner,store)"},"eq-locale":{"value":"eq(locales.fr-FR.name,Nom-du-produit)"},"like-locale":{"value":"like(locales.es-ES.description,*descripción*)"}}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}},{"name":"include_hierarchies","in":"query","description":"When true, includes hierarchy objects in the response alongside nodes","required":false,"schema":{"type":"boolean","default":false}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a list of nodes","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"description":"An array of nodes or hierarchies.","type":"array","items":{"oneOf":[{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"},{"type":"object","required":["id","type","meta","relationships","attributes"],"properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description for a hierarchy.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes_hierarchy"},"relationships":{"type":"object","properties":{"children":{"description":"The child nodes related to the hierarchy.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships_hierarchy"},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a hierarchy is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the hierarchy has child nodes.","type":"boolean"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"hierarchy"}],"discriminator":{"propertyName":"type","mapping":{"node":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"},"hierarchy":{"type":"object","required":["id","type","meta","relationships","attributes"],"properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description for a hierarchy.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes_hierarchy"},"relationships":{"type":"object","properties":{"children":{"description":"The child nodes related to the hierarchy.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships_hierarchy"},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a hierarchy is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the hierarchy has child nodes.","type":"boolean"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"hierarchy"}}}}},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"}},"title":"nodes_or_hierarchies"},"examples":{"get-all-nodes":{"value":{"data":[{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","type":"node","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}},{"type":"node","id":"b2f5e53e-de3c-4548-98da-120f8b185d34","attributes":{"description":"All Dress Shoes","locales":{"fr-FR":{"name":"Chaussures habillées","description":"Toutes les chaussures habillées"}},"name":"Dress Shoes","slug":"dress-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/products"}}},"meta":{"created_at":"2024-01-11T19:50:21.729Z","owner":"store","sort_order":3,"updated_at":"2024-01-11T19:50:21.729Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"b2f5e53e-de3c-4548-98da-120f8b185d34","name":"Dress Shoes","slug":"dress-shoes","locales":{"fr-FR":{"name":"Node 2 in French"}}}]}},{"type":"hierarchy","id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","attributes":{"description":"Shoes Category","locales":{"fr-FR":{"name":"Chaussures","description":"Catégorie de chaussures"}},"name":"Shoes","slug":"shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/children"}}},"meta":{"created_at":"2024-01-10T20:16:35.343Z","owner":"store","updated_at":"2024-01-10T20:30:50.867Z","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}}]}}],"meta":{"results":{"total":3}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get All Product Tags

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get All Product Tags"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all product tags for a store. A store can view the tags associated with the organization to which the store belongs. However, an organization can only view the tags associated with the organization.
 

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all the product tags.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"An array of tags.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a tag is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `tag`.","type":"string","enum":["tag"]},"attributes":{"type":"object","properties":{"value":{"type":"string","description":"The text value of the tag."}}},"meta":{"type":"object","properties":{"x_request_id":{"type":"string","description":"A unique request ID is generated when a tag is created."},"created_at":{"type":"string","description":"The date and time a tag is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a tag is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]}}}},"title":"tag"}},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}},"title":"multi_tag"},"examples":{"list-tags":{"summary":"Get all tags","value":{"data":[{"type":"tag","id":"a88aac35-54de-40c2-bb4b-f1c57624db27","attributes":{"value":"shirts"},"meta":{"created_at":"2024-03-20T15:56:40.014Z","owner":"store","updated_at":"2024-03-20T15:56:40.014Z"}},{"type":"tag","id":"6782e020-fefd-431e-9dea-b59d249c2c5e","attributes":{"value":"shoes"},"meta":{"created_at":"2024-03-20T15:56:40.014Z","owner":"store","updated_at":"2024-03-20T15:56:40.014Z"}}],"meta":{"results":{"total":2}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all products(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all your products in the Product Experience Manager system.

You can also use `include` to retrieve top-level resources, such as files or images, and key attribute data, such as SKU or slug for component products in a product bundle. With this option, you can get more information about the products in a product bundle in your store front, improving the buying experience for your shoppers.

#### Pagination

This endpoint supports offset-based pagination using `page[offset]` and `page[limit]` query parameters.

:::caution Planned pagination changes — on or after 1 September 2026

The pagination links returned by this endpoint currently differ from the Elastic Path Commerce Cloud platform standard. Specifically, the `current` link is not returned, `first`/`last` are not always present, `prev` is incorrectly omitted on the second page, and `next` is incorrectly omitted on the second-to-last page.

On or after **1 September 2026**, this endpoint will be updated so that `current` and `first` are always present, `last` is present on every page except the final page, `next` is present on every page except the last, and `prev` is present on every page except the first. See the [links](/docs/api/pxm/products/get-all-products#links) schema for full details.

If your integration iterates through pages using these links, please verify that it will handle the updated behaviour correctly before this date.

:::

#### Filtering

 Many Commerce API endpoints support filtering. The general syntax is described in [**Filtering**](/guides/Getting-Started/filtering).

 The following attributes and operators are supported.

| Operator                  | Attribute                                                                                                                                               | Description                                                                                                                                                                                                                                             | Example                                          |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------- |
| `eq`                      | `id`, `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `name`, `templates`, `commodity_type`, `owner`, `product_types`, `parent_id`, `component_option_id`, `tags`, `status`, `has_nodes (false only)`, `created_at`, `updated_at`, `external_ref`, `description` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. For `product_types`, you can only specify one product type. **Note:** `has_nodes` can only be filtered as `false`. **Note:** `component_option_id` matches when a bundle includes that product id as a component option. | `?filter=eq(name,some-name)` |
| `like`                    | `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `name`, `tags`, `description`, `external_ref`                                                        | Like. Checks if the operand contains the specified string. Wildcards are supported.                                                                                                                                                                     | `?filter=like(name,*some-name*)`                 |
| `in`                      | `id`, `name`, `sku`, `slug`, `upc_ean`, `manufacturer_part_num`, `product_types`, `parent_id`, `component_option_id`, `tags`, `external_ref`                                   | Checks if the values are included in the specified list. If they are, the condition is true. For `product_types`, you can specify more than one product type.                                                                                           | `?filter=in(id,some-id)`                         |
| `gt`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Greater than. Checks if the value of the field is greater than the given value.                                                                                                                                                                         | `?filter=gt(updated_at,2024-01-01T00:00:00Z)`    |
| `ge`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Greater than or equal to. Checks if the value of the field is greater than or equal to the given value.                                                                                                                                                 | `?filter=ge(created_at,2023-01-01T00:00:00Z)`    |
| `lt`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Less than. Checks if the value of the field is less than the given value.                                                                                                                                                                               | `?filter=lt(updated_at,2025-01-01T00:00:00Z)`    |
| `le`                      | `id`, `created_at`, `updated_at`, `external_ref`                                                                                                        | Less than or equal to. Checks if the value of the field is less than or equal to the given value.                                                                                                                                                       | `?filter=le(created_at,2022-01-01T00:00:00Z)`    |
| `eq` (extensions)         | `extensions.book.isbn`                                                                                                                                  | Filters using a nested extension field.                                                                                                                                                                                                                 | `?filter=eq(extensions.book.isbn,1765426)`       |
| `eq` (shopper_attributes) | `shopper_attributes.color`                                                                                                                              | Filters using a shopper custom attribute field.                                                                                                                                                                                                         | `?filter=eq(shopper_attributes.color,red)`       |
| `eq` (admin_attributes)   | `admin_attributes.warehouse`                                                                                                                            | Filters using an admin custom attribute field.                                                                                                                                                                                                          | `?filter=eq(admin_attributes.warehouse,US-EAST)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}},{"name":"filter","in":"query","description":"Many Commerce API endpoints support filtering. The general syntax is described [**here**](/guides/Getting-Started/filtering).\n\nFor more information about the attributes and operators that are supported, see [Get all products](/docs/api/pxm/products/get-all-products).\n","style":"form","explode":true,"schema":{"type":"string"},"examples":{"eq":{"value":"eq(name,some-name)"},"like":{"value":"like(name,*some-name*)"},"in":{"value":"in(id,some-id)"}}},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"items":{"type":"string","enum":["files","main_image","component_products"]}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a list of all products.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included_response"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}},"title":"multi_product_response"},"examples":{"list-products":{"value":{"data":[{"type":"product","id":"9c85b276-09b4-488e-a59c-c561bae14c9e","attributes":{"commodity_type":"physical","custom_inputs":{"back":{"name":"T-Shirt Back","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false},"front":{"name":"T-Shirt Front","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false}},"description":"T-shirt.","mpn":"1234-5678-TTTT","name":"T-Shirt","sku":"97805","slug":"97805","status":"live","upc_ean":"12345656","tags":["tag1","tag2"],"extensions":{"products(size)":{"widthMM":600,"fuelType":"electric","hasUKPlug":true,"online":null}}},"relationships":{"children":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/children"}},"component_products":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/variations"}}},"meta":{"created_at":"2022-08-18T14:25:57.391Z","owner":"store","product_types":["standard"],"updated_at":"2022-08-18T14:25:57.391Z"}}],"meta":{"results":{"total":1}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all variation options

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all variation options"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/variations/{variationID}/options"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all variation options

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns all variation options.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when an option is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation-option`.","type":"string","enum":["product-variation-option"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string"},"description":{"description":"A human-recognizable description for the option.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"}}},"meta":{"type":"object","properties":{"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["organization","store"]},"created_at":{"type":"string","description":"The date and time an option is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time an option is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"}}}}}},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":3}}}}}},"title":"multi_options"},"examples":{"list-variations":{"value":{"data":[{"type":"product-variation-option","id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","attributes":{"description":"Our most popular color","name":"Blue","sort_order":0},"meta":{"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}},{"type":"product-variation-option","id":"fbe73839-58a2-41b4-aca6-cb0724668c97","attributes":{"description":"Our second most popular color","name":"Red"},"meta":{"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}}],"meta":{"results":{"total":2}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all variations

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all variations"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/variations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all variations

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all variations.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a variation.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation`.","type":"string","enum":["product-variation"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The name of a variation.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"}}},"meta":{"type":"object","properties":{"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated when an option is created."},"name":{"type":"string","description":"A human recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed."},"description":{"type":"string","description":"A human recognizable description of the option."},"created_at":{"type":"string","description":"The date and time an option is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time an option is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"modifiers":{"type":"array","description":"The modifiers associated with this option.","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier generated when a modifier is created."},"type":{"type":"string","description":"The type of modifier.","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"type":"string","nullable":true,"description":"Required for non-builder modifiers. The value of the modifier type."},"seek":{"type":"string","nullable":true,"description":"Required for builder modifiers. The sub-string to find and replace."},"set":{"type":"string","nullable":true,"description":"Required for builder modifiers. The value to replace matches of the seek string."},"owner":{"type":"string","nullable":true,"description":"The owner of the modifier, either `organization` or `store`.","enum":["organization","store"]}}}}}}},"owner":{"type":"string","description":"The owner of the resource, either `organization` or `store`.","enum":["organization","store"]},"created_at":{"type":"string","description":"The date and time a variation is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a variation is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"}}}}}},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":3}}}}}},"title":"multi_variations"},"examples":{"list-variations":{"value":{"data":[{"type":"product-variation","id":"c1ccccba-53e4-46b5-aed8-94f32823148a","attributes":{"name":"Size","sort_order":1},"meta":{"options":[{"id":"057a50ba-1afb-4944-9637-bd9b568a9f39","name":"Large","description":"Large size","sort_order":3,"created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"},{"id":"fa191e68-9bba-49f9-8e12-056c4e8f50e2","name":"Medium","description":"Medium size","sort_order":2,"created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"},{"id":"112d1c5c-d149-453e-b208-89470968bacf","name":"Small","description":"Small size","sort_order":1,"created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}],"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}},{"type":"product-variation","id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","attributes":{"name":"Paint Color"},"meta":{"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}}],"meta":{"results":{"total":2}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get child products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get child products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/children"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get child products

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a list of child products for the specified parent product ID.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included_response"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}},"title":"multi_product_response"},"examples":{"list-products":{"value":{"data":[{"type":"product","id":"4d32b816-4397-4a71-b875-4e4ea3ce6745","attributes":{"commodity_type":"physical","name":"Jeans","sku":"jeansRed","slug":"jeansRed","status":"live"},"relationships":{"base_product":{"data":{"type":"product","id":"571e366f-17e6-4e51-8239-b3cc8ee1144d"}},"children":{"data":[]},"component_products":{"data":[],"links":{"self":"/products/4d32b816-4397-4a71-b875-4e4ea3ce6745/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/4d32b816-4397-4a71-b875-4e4ea3ce6745/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/4d32b816-4397-4a71-b875-4e4ea3ce6745/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/4d32b816-4397-4a71-b875-4e4ea3ce6745/relationships/variations"}}},"meta":{"created_at":"2024-01-05T10:29:44.603Z","owner":"store","product_types":["child"],"updated_at":"2024-01-05T10:29:45.155Z","variation_matrix":{},"child_variations":[{"id":"119b2b76-0014-4077-826e-ae80ff207393","name":"Size","options":null,"option":{"id":"fad253ad-4485-4b35-8e3b-b475ad28e78d","name":"Medium","description":"Medium"}},{"id":"10ceafef-7ac9-4352-9797-4825a1671482","name":"Colour","options":null,"option":{"id":"b8128e51-1b0a-4b16-9eda-bb783b17026b","name":"Red","description":"#EE2238"}}]}}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a custom relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a custom relationship"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/custom-relationships/{customRelationshipSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets a Custom Relationship.

To see a list of custom relationships a product is attached to, see [Get all Custom Relationships attached to a Product](/docs/api/pxm/products/list-attached-custom-relationship).

To see a list of products that a product is related to, see [Get all Related Products of a Products' attached Custom Relationship](/docs/api/pxm/products/get-related-products-of-a-product-id).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"customRelationshipSlug","in":"path","schema":{"type":"string","example":"CRP_electric_devices_2024"},"required":true,"description":"A custom relationship slug."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a custom relationship with the following attributes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a custom relationship is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `custom-relationship`.","type":"string","enum":["custom-relationship"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"description":"The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.","type":"string","example":"Related Products"},"description":{"description":"A description of the custom relationship.","type":"string","example":"A list of related products shown on the PDP."},"slug":{"description":"A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string","example":"CRP_related_products","pattern":"^[A-Za-z0-9._-]+$"},"sort_order":{"description":"The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5},"external_name":{"description":"The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.","nullable":true,"type":"string","example":"Similar items to consider"},"external_description":{"description":"The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.","nullable":true,"type":"string","example":"Check out these similar products that may also meet your needs or match your preferences."},"bi_directional":{"type":"boolean","description":"Is this relationship one way or bi-directional `true` or `false`. Default is false","default":false}},"title":"req_attributes_custom_relationship"},"meta":{"type":"object","required":["owner","timestamps"],"properties":{"owner":{"description":"The owner of the resource.","type":"string","example":"store"},"timestamps":{"type":"object","required":["created_at","updated_at"],"properties":{"created_at":{"description":"The date and time the resource is created.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"},"updated_at":{"description":"The date and time the resource is updated.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"}}}}}},"title":"custom_relationship"}},"title":"single_custom_relationship"},"examples":{"get-custom-relationship":{"summary":"Get","value":{"data":{"type":"custom-relationship","id":"f3297ee8-da90-45e9-ae56-a2654aebbdfe","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","sort_order":5,"external_name":"Similar items to consider","external_description":"Check out these similar products that may also meet your needs or match your preferences.","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all custom relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all custom relationships"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/custom-relationships"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets all Custom Relationships. 

To see a list of custom relationships a product is attached to, see [Get all Custom Relationships attached to a Product](/docs/api/pxm/products/list-attached-custom-relationship).

To see a list of products that a product is related to, see [Get all Related Products of a Products' attached Custom Relationship](/docs/api/pxm/products/get-related-products-of-a-product-id).

### Filtering

 Many Commerce API endpoints support filtering. The general syntax is described in [**Filtering**](/guides/Getting-Started/filtering).

 The following attributes and operators are supported.

 | Operator | Attribute | Description | Example |
 | :--- |:---|:---|:---|
 | `eq` | `owner`, `slug` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. | `filter=eq(owner,store)` |
 | `in` | `slug`          | In. Checks if a value exists in a given list of values. If the value matches any item in the list, the condition is true. | `filter=in(slug,slug-1,slug-2,slug-3)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}},{"name":"filter","in":"query","description":"Many Commerce API endpoints support filtering. The general syntax is described [**here**](/guides/Getting-Started/filtering).\n","style":"form","explode":true,"schema":{"type":"string"},"examples":{"eq-owner":{"value":"eq(owner,store)"}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a list of all custom relationships.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a custom relationship is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `custom-relationship`.","type":"string","enum":["custom-relationship"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"description":"The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.","type":"string","example":"Related Products"},"description":{"description":"A description of the custom relationship.","type":"string","example":"A list of related products shown on the PDP."},"slug":{"description":"A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string","example":"CRP_related_products","pattern":"^[A-Za-z0-9._-]+$"},"sort_order":{"description":"The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5},"external_name":{"description":"The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.","nullable":true,"type":"string","example":"Similar items to consider"},"external_description":{"description":"The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.","nullable":true,"type":"string","example":"Check out these similar products that may also meet your needs or match your preferences."},"bi_directional":{"type":"boolean","description":"Is this relationship one way or bi-directional `true` or `false`. Default is false","default":false}},"title":"req_attributes_custom_relationship"},"meta":{"type":"object","required":["owner","timestamps"],"properties":{"owner":{"description":"The owner of the resource.","type":"string","example":"store"},"timestamps":{"type":"object","required":["created_at","updated_at"],"properties":{"created_at":{"description":"The date and time the resource is created.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"},"updated_at":{"description":"The date and time the resource is updated.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"}}}}}},"title":"custom_relationship"}},"links":{"type":"object","description":"Links are used to allow you to move between requests.","properties":{"first":{"description":"Always the first page.","type":"string","example":"/pcm/custom_relationships?page[offset]=0&page[limit]=10"},"last":{"description":"This is `null` if there is only one page.","type":"string","example":"/pcm/custom_relationships?page[offset]=20&page[limit]=10"},"next":{"description":"This is `null` if there is only one page.","type":"string","example":"/pcm/custom_relationships?page[offset]=10&page[limit]=10"},"prev":{"description":"This is `null` if you on the first page.","type":"string","example":"/pcm/custom_relationships?page[offset]=8&page[limit]=10"}},"title":"multi_links_cr"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"}},"title":"multi_custom_relationships"},"examples":{"list-custom-relationships":{"value":{"data":[{"id":"f3297ee8-da90-45e9-ae56-a2654aebbdfe","type":"custom-relationship","attributes":{"name":"Kitchen electrics","description":"Kitchen electric devices","slug":"CRP_kitchen_individual_devices","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}},{"id":"21b1315b-c47f-4766-85bf-7bf0f94d73b6","type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","bi_directional":true},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}},{"id":"e390ff7e-efc4-4769-90d2-fceabcc1e2cd","type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","sort_order":5,"external_name":"Similar items to consider","external_description":"Check out these similar products that may also meet your needs or match your preferences.","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}}],"links":{"last":"/pcm/custom_relationships?page[offset]=29&page[limit]=1","next":"/pcm/custom_relationships?page[offset]=1&page[limit]=1"},"meta":{"results":{"total":3}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a hierarchy(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a hierarchy"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/hierarchies/{hierarchyID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the specified hierarchy.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a hierarchy with the following attributes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","meta","relationships","attributes"],"properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description for a hierarchy.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes_hierarchy"},"relationships":{"type":"object","properties":{"children":{"description":"The child nodes related to the hierarchy.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships_hierarchy"},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a hierarchy is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the hierarchy has child nodes.","type":"boolean"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"hierarchy"}},"title":"single_hierarchy"},"examples":{"get-hierarchy":{"value":{"data":{"type":"hierarchy","id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","attributes":{"description":"Shoes Category","locales":{"fr-FR":{"name":"Chaussures","description":"Catégorie de chaussures"}},"admin_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"shopper_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"name":"Shoes","slug":"shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/children"}}},"meta":{"created_at":"2024-01-10T20:16:35.343Z","owner":"store","updated_at":"2024-01-10T20:16:35.343Z","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}}]}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a node(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a node"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a node from a hierarchy.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a node with the following attributes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"title":"single_node"},"examples":{"get-node":{"value":{"data":{"type":"node","id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","attributes":{"description":"All Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Toutes les chaussures de ballet"}},"admin_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"shopper_attributes":{"cost_of_goods":"42.0","charge_type":"credit card"},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"parent":{"data":{"type":"node","id":"14e8e15a-7214-435d-bccb-6ae9b570d683"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","parent_name":"Shoes","sort_order":2,"updated_at":"2024-01-11T19:19:50.087Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all hierarchies(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all hierarchies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/hierarchies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all hierarchies

#### Pagination

This endpoint supports offset-based pagination using `page[offset]` and `page[limit]` query parameters.

:::caution Planned pagination changes — on or after 1 September 2026

The pagination links returned by this endpoint currently differ from the Elastic Path Commerce Cloud platform standard. Specifically, the `current` link is not returned, `first`/`last` are not always present, `prev` is incorrectly omitted on the second page, and `next` is incorrectly omitted on the second-to-last page.

On or after **1 September 2026**, this endpoint will be updated so that `current` and `first` are always present, `last` is present on every page except the final page, `next` is present on every page except the last, and `prev` is present on every page except the first. See the [links](#links) schema for full details.

If your integration iterates through pages using these links, please verify that it will handle the updated behaviour correctly before this date.

:::

#### Filtering
             
Many Commerce API endpoints support filtering. The general syntax is described in [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator        | Attribute                                                                                 | Description                                                                                      | Example                                  |
|----------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|------------------------------------------|
| `eq`           | `id`, `hierarchy_id`, `owner`, `parent_id`, `name`, `slug`, `description`, `has_children`, `created_at`, `updated_at`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.id`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Equals. Checks if the value of the attribute matches the specified value. | `filter=eq(name,some-name)`, `filter=eq(locales.fr-FR.name,Nom-du-produit)` |
| `in`           | `id`, `hierarchy_id`,  `parent_id`, `breadcrumbs.id`                                              | Checks if the value of the attribute is included in the specified list.                        | `filter=in(id,1,2,3,4)`                 |
| `lt`, `le`, `gt`, `ge` | `id`, `hierarchy_id`,  `parent_id`, `created_at`, `updated_at`         | Comparison operators. `lt`: Less than, `le`: Less than or equal to, `gt`: Greater than, `ge`: Greater than or equal to. | `filter=lt(id,100)`, `filter=ge(created_at,2022-01-01)` |
| `like`         | `name`, `slug`, `description`, `locales.[locale].name`, `locales.[locale].description`, `breadcrumbs.name`, `breadcrumbs.slug`, `breadcrumbs.locales.[locale].name` | Like. Checks if the attribute contains the specified string (wildcards supported).            | `filter=like(name,*some-name*)`, `filter=like(locales.es-ES.description,*descripción*)` |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}},{"name":"filter","in":"query","description":"Many Commerce API endpoints support filtering. The general syntax is described [**here**](/guides/Getting-Started/filtering).\n","style":"form","explode":true,"schema":{"type":"string"},"examples":{"eq":{"value":"eq(name,some-name)"},"like":{"value":"like(name,*some-name*)"},"in":{"value":"in(id,some-id)"},"lt":{"value":"lt(id,100)"},"le":{"value":"le(created_at,2023-01-01)"},"gt":{"value":"gt(updated_at,2023-01-01)"},"ge":{"value":"ge(parent_id,500)"},"eq-owner":{"value":"eq(owner,store)"},"eq-locale":{"value":"eq(locales.fr-FR.name,Nom-du-produit)"},"like-locale":{"value":"like(locales.es-ES.description,*descripción*)"}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a list of all hierarchies.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","meta","relationships","attributes"],"properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description for a hierarchy.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes_hierarchy"},"relationships":{"type":"object","properties":{"children":{"description":"The child nodes related to the hierarchy.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships_hierarchy"},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a hierarchy is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the hierarchy has child nodes.","type":"boolean"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"hierarchy"}},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"}},"title":"multi_hierarchy"},"examples":{"list-hierarchies":{"value":{"data":[{"type":"hierarchy","id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","attributes":{"description":"Shoes Category","locales":{"fr-FR":{"name":"Chaussures","description":"Catégorie de chaussures"}},"name":"Shoes","slug":"shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/children"}}},"meta":{"created_at":"2024-01-10T20:16:35.343Z","owner":"store","updated_at":"2024-01-10T20:30:50.867Z","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}}]}}],"links":{"last":"/pcm/hierarchies?page[offset]=29&page[limit]=1","next":"/pcm/hierarchies?page[offset]=1&page[limit]=1"},"meta":{"results":{"total":30}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Job Errors

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Job Errors"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/jobs/{jobID}/errors"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get Job Errors

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"jobID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the job."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","required":["results"],"properties":{"results":{"type":"object","required":["total"],"properties":{"total":{"type":"integer","description":"Total number of job errors for this job."}}}}},"data":{"type":"array","description":"An array of job errors.","items":{"type":"object","properties":{"type":{"description":"This represents the type of resource object being returned. Always `pim-job-error`.","type":"string","example":"pim-job-error","enum":["pim-job-error"]},"id":{"description":"A unique identifier for a job error generated when a job error is created.","type":"string"},"attributes":{"type":"object","properties":{"message":{"description":"A description of an error message.","type":"string","example":"data.attributes.sku: Must be unique amongst products."}}}}}}},"title":"errors"},"examples":{"errors":{"summary":"Errors Returned","value":{"data":[{"type":"pim-job-error","id":"2950cae3-1050-4c43-9fbd-2aa60dc5c249","attributes":{"message":"data.attributes.sku: Must be unique amongst products."}}],"meta":{"results":{"total":1}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a Job(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Job"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/jobs/{jobID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a Job

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"jobID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the job."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a job with the following attributes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a job is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `pim-job`.","type":"string","enum":["pim-job"]},"attributes":{"type":"object","required":["started_at","completed_at","created_at","updated_at","type","status"],"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true},"completed_at":{"type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true,"description":"The date and time a job is completed."},"created_at":{"type":"string","description":"The date and time a job is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a job is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"type":{"type":"string","description":"The status of a job.\n\n* `pending` - Commerce has received the request but is currently busy processing other requests.\n* `started` - Commerce has started processing the job.\n* `success` - The job has successfully completed.\n* `failed` - The job has failed.\n","enum":["child-products","product-import","product-export","hierarchy-duplicate","pricebook-import","pricebook-delete","hierarchy-delete","indexing-job","attach-nodes"]},"status":{"type":"string","enum":["pending","cancelled","cancelling","started","success","failed"]}}},"meta":{"type":"object","required":["x_request_id"],"properties":{"x_request_id":{"type":"string","description":"Applies to all job types. A unique request ID is generated when a job is created."},"copied_from":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated."},"hierarchy_id":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID."},"file_locations":{"type":"array","nullable":true,"description":"If the job type is `product_export`, a link to the file is created when running a job.","items":{"type":"string"}},"filter":{"type":"string","nullable":true,"description":"The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export."}}}},"title":"job"}},"title":"single"},"examples":{"started":{"summary":"Started Job","value":{"data":{"type":"pim-job","id":"1ea62172-57f6-45e5-a708-ab5bd634e3f9","attributes":{"started_at":null,"completed_at":null,"created_at":"2024-01-05T13:46:41.695Z","status":"started","type":"product-import","updated_at":"2024-01-05T13:46:42.07Z"},"meta":{"x_request_id":"7e832a26-d615-4305-b26a-e33c9c2fc06a"}}}},"successful":{"summary":"Product Import Job","value":{"data":{"type":"pim-job","id":"1ea62172-57f6-45e5-a708-ab5bd634e3f9","attributes":{"completed_at":"2024-01-05T13:46:42.142Z","created_at":"2024-01-05T13:46:41.695Z","started_at":"2024-01-05T13:46:42.07Z","status":"success","type":"product-import","updated_at":"2024-01-05T13:46:42.07Z"},"meta":{"x_request_id":"7e832a26-d615-4305-b26a-e33c9c2fc06a"}}}},"product-export":{"summary":"Product Export Job","value":{"data":{"type":"pim-job","id":"7e1b9ba1-c844-4556-9b16-4ae3f0988b0f","attributes":{"completed_at":"2024-01-05T15:27:23.663Z","created_at":"2024-01-05T15:27:23.161Z","started_at":"2024-01-05T15:27:23.65Z","status":"success","type":"product-export","updated_at":"2024-01-05T15:27:23.65Z"},"meta":{"file_locations":[],"filter":"eq(sku,product-1)","x_request_id":"fad8c5c0-9546-4e0c-b68e-8a2d809891e5"}}}},"hierarchy-duplicate":{"summary":"Hierarchy Duplicate Job","value":{"data":{"type":"pim-job","id":"5ba1c98d-87b8-4d63-b2ed-3d3c6c876523","attributes":{"completed_at":"2024-01-08T11:56:29.257Z","created_at":"2024-01-08T11:56:27.553Z","started_at":"2024-01-08T11:56:29.222Z","status":"success","type":"hierarchy-duplicate","updated_at":"2024-01-08T11:56:29.237Z"},"meta":{"copied_from":"5b912d00-db5a-4e18-86f2-3a652967ee48","hierarchy_id":"c05bfefc-8de4-43ea-858b-eb8984ad9f8f","x_request_id":"an-x-request-id"}}}},"build-child-products":{"summary":"Build Child Products Job","value":{"data":{"type":"pim-job","id":"14a0a190-cd03-4d7f-a449-e2051ac539ea","attributes":{"completed_at":"2024-01-08T11:58:19.113Z","created_at":"2024-01-08T11:58:04.416Z","started_at":"2024-01-08T11:58:19.067Z","status":"success","type":"child-products","updated_at":"2024-01-08T11:58:19.067Z"},"meta":{"x_request_id":"an-x-request-id"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a modifier(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a modifier"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/variations/{variationID}/options/{optionID}/modifiers/{modifierID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a modifier

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"optionID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the option."},{"name":"modifierID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the modifier."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns the specified modifier.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"A unique identifier for a modifier that is generated automatically when a modifier is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation-modifier`.","type":"string","enum":["product-variation-modifier"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"type":{"description":"You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n","type":"string","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"description":"Required for non-builder modifiers. The value of the modifier type.","type":"string"},"seek":{"description":"Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.","type":"string"},"set":{"description":"Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.","type":"string"},"reference_name":{"description":"The name of the modifier.","type":"string"}}},"meta":{"type":"object","description":"The owner of the resource, either `organization` or `store`.","properties":{"owner":{"type":"string","enum":["organization","store"]}}}}}},"title":"single_modifier"},"examples":{"get-variation-modifier":{"value":{"data":{"type":"product-variation-modifier","id":"68ec4892-9e4c-4154-a9fd-f5a9fb1f6878","attributes":{"type":"sku_equals","value":"newSku"},"meta":{"owner":"store"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a node's products(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a node's products"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the products associated with the specified hierarchy node from a published catalog. Products must be in a live status. If the products have been curated using the update a hierarchy node endpoint, then the products are returned in the order specified in the `curated_products` attribute in the body of the update a hierarchy node request. A product that is curated has the "curated_product": true attribute displayed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the node's products","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included_response"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}},"title":"multi_product_response"},"examples":{"get-node-products":{"value":{"data":[{"type":"product","id":"9c85b276-09b4-488e-a59c-c561bae14c9e","attributes":{"commodity_type":"physical","custom_inputs":{"back":{"name":"T-Shirt Back","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false},"front":{"name":"T-Shirt Front","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false}},"description":"T-shirt.","mpn":"1234-5678-TTTT","name":"T-Shirt","sku":"97805","slug":"97805","status":"live","upc_ean":"12345656","tags":["tag1","tag2"],"extensions":{"products(size)":{"widthMM":600,"fuelType":"electric","hasUKPlug":true,"online":null}}},"relationships":{"children":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/children"}},"component_products":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/variations"}}},"meta":{"created_at":"2022-08-18T14:25:57.391Z","owner":"store","product_types":["standard"],"updated_at":"2022-08-18T14:25:57.391Z"}}],"meta":{"results":{"total":1}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Bundle Component Product Relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Bundle Component Product Relationships"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/relationships/component_products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all the products included in the specified bundle product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all Component Products relationships.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of a product component generated when a product is created."},"type":{"type":"string","enum":["product"],"description":"This represents the type of resource object being returned. Always `product`."}}}}},"title":"component_products_response"},"examples":{"product-template-relationships":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"product"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"product"}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all product file relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all product file relationships"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/relationships/files"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all files that are associated with the specified product.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all product file relationships.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the file."},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `file`.","enum":["file"]},"meta":{"type":"object","properties":{"created_at":{"type":"string","description":"The date and time the file relationship was created.","format":"date-time","nullable":true},"tags":{"type":"array","description":"The file tags.","items":{"type":"string"}}}}}}}},"title":"file_response"},"examples":{"product-file-relationships":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"file"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"file"}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Main Image Relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Main Image Relationships"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/relationships/main_image"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get Main Image Relationships

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all product variation relationships","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"A file object representing the main image, or null if no main image is set.","type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for the image file generated automatically when a file is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `file`.","type":"string","enum":["file"]}}}},"title":"main_image_response"},"examples":{"product-main-image-relationships":{"value":{"data":{"type":"file","id":"file-1"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a Product Tag

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a Product Tag"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/tags/{tagID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a product tag for a store. A store can view the tags associated with the organization to which the store belongs. However, an organization can only view the tags associated with the organization.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"tagID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the tag."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a product tag with the following attributes.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a tag is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `tag`.","type":"string","enum":["tag"]},"attributes":{"type":"object","properties":{"value":{"type":"string","description":"The text value of the tag."}}},"meta":{"type":"object","properties":{"x_request_id":{"type":"string","description":"A unique request ID is generated when a tag is created."},"created_at":{"type":"string","description":"The date and time a tag is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a tag is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]}}}},"title":"tag"}},"title":"single_tag"},"examples":{"get-tag":{"summary":"Get a tag","value":{"data":{"type":"tag","id":"9879a8f5-0da2-4be6-91f6-a0f09d1c77a9","attributes":{"value":"tables"},"meta":{"created_at":"2024-03-20T18:37:43.398Z","owner":"organization","updated_at":"2024-03-20T18:37:43.398Z"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all product template relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all product template relationships"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/relationships/templates"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all product template relationships

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all product template relationships.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a template generated when a template is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `template`.","type":"string","enum":["template"]}}}}},"title":"template_response"},"examples":{"product-template-relationships":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"template"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"template"}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all product variation relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all product variation relationships"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/relationships/variations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all product variation relationships

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all product variation relationships.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a variation is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation`.","type":"string","enum":["product-variation"]},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a resource is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"}}}}}}},"title":"variations_response"},"examples":{"product-variation-relationships":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"product-variation"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"product-variation"}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a product(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a product by its identifier. 

You can also use `include=component_products` to retrieve top-level resources, such as files or images, and key attribute data, such as SKU or slug for component products in a product bundle. With this option, you can get more information about the products in a product bundle in your store front, improving the buying experience for your shoppers.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."},{"name":"include","in":"query","description":"Using the include parameter, you can retrieve top-level resources.\n\n- Files or main image. For example, `include=files,main_image`.\n- Component product data. For example, `include=component_products`.\n- Key attribute data, such as SKU or slug.\n","required":false,"style":"form","explode":false,"schema":{"items":{"type":"string","enum":["files","main_image","component_products"]}}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns a product by its identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included_response"}},"title":"single_product_response"},"examples":{"get-product":{"summary":"Product","value":{"data":{"type":"product","id":"f5bd4e59-a95f-4bda-bfe6-0f34f47ac94b","attributes":{"commodity_type":"physical","description":"This electric model offers an induction heating element and convection oven.","mpn":"BE-R-1111-aaaa-1a1a","name":"BestEver Range, Model 1a1a","sku":"BE-Range-1a1a","slug":"bestever-range-1a1a","status":"draft","upc_ean":"111122223333","tags":["tag1","tag2"],"extensions":{"products(size)":{"widthMM":600,"fuelType":"electric","hasUKPlug":true,"online":null}}},"relationships":{"custom_relationships":{"data":[],"links":{"self":"/products/f5bd4e59-a95f-4bda-bfe6-0f34f47ac94b/custom-relationships","CRP_summer_session":"/products/f5bd4e59-a95f-4bda-bfe6-0f34f47ac94b/custom-relationships/CRP_summer_session/products","CRP_winter_session":"/products/f5bd4e59-a95f-4bda-bfe6-0f34f47ac94b/custom-relationships/CRP_winter_session/products"}},"files":{"data":[],"links":{"self":"/products/f5bd4e59-a95f-4bda-bfe6-0f34f47ac94b/relationships/files"}},"templates":{"data":[],"links":{"self":"/products/f5bd4e59-a95f-4bda-bfe6-0f34f47ac94b/relationships/templates"}}},"meta":{"created_at":"2023-09-28T10:43:41.72Z","owner":"organization","product_types":["standard"],"updated_at":"2023-09-28T10:43:41.72Z","variation_matrix":{},"custom_relationships":["CRP_summer_session","CRP_winter_session"]}}}},"get-product-bundle":{"summary":"Bundle","value":{"data":{"type":"product","id":"495f5c48-c747-4540-86fd-40380bf2df91","attributes":{"commodity_type":"physical","components":{"games":{"name":"Games","options":[{"id":"1a499918-2ec0-468d-b7b9-f09eab2f6ad8","type":"product","quantity":2,"sort_order":15,"default":true}],"sort_order":10}},"name":"DOOM Bundle","status":"draft"},"relationships":{"children":{"data":[],"links":{"self":"/products/495f5c48-c747-4540-86fd-40380bf2df91/children"}},"component_products":{"data":[],"links":{"self":"/products/495f5c48-c747-4540-86fd-40380bf2df91/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/495f5c48-c747-4540-86fd-40380bf2df91/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/495f5c48-c747-4540-86fd-40380bf2df91/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/495f5c48-c747-4540-86fd-40380bf2df91/relationships/variations"}}},"meta":{"created_at":"2024-01-08T13:36:53.658Z","owner":"organization","product_types":["bundle"],"updated_at":"2024-01-08T13:36:53.658Z","variation_matrix":{}}}}},"get-product-bundle-quantity-config":{"summary":"Bundle with Quantity Configuration","description":"Retrieve a bundle where each selected option can have a configurable quantity. In this example, syrup is optional (0-2 types) with up to 3 pumps per syrup, and exactly one coffee type must be selected.","value":{"data":{"type":"product","id":"143e9ded-b549-4631-831c-d27f5fb2fe2e","attributes":{"name":"Coffee Bundle","description":"A customizable coffee bundle with optional syrups and coffee options","sku":"COFFEE-BUNDLE-001","commodity_type":"physical","status":"live","components":{"syrup":{"name":"Syrup Selection","min":0,"max":2,"options":[{"id":"vanilla-id","type":"product","quantity":1,"min":1,"max":3,"default":true},{"id":"salted-caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"hazelnut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"toffee-nut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"pumpkin-spice-id","type":"product","quantity":1,"min":1,"max":3}]},"coffee":{"name":"Coffee Selection","min":1,"max":1,"options":[{"id":"cappuccino-id","type":"product","quantity":1,"default":true},{"id":"espresso-id","type":"product","quantity":1},{"id":"latte-id","type":"product","quantity":1}]}}},"relationships":{"children":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/children"}},"component_products":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/templates"}},"variations":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/variations"}}},"meta":{"created_at":"2024-04-14T10:34:00.000Z","owner":"organization","product_types":["bundle"],"updated_at":"2024-04-14T10:34:00.000Z","variation_matrix":{}}},"included":{"main_images":[],"files":[]}}},"get-product-component-parent":{"summary":"Parent Product","value":{"data":{"type":"product","id":"571e366f-17e6-4e51-8239-b3cc8ee1144d","attributes":{"commodity_type":"physical","name":"Jeans","sku":"jeans","slug":"jeans","status":"live"},"relationships":{"children":{"data":[],"links":{"self":"/products/571e366f-17e6-4e51-8239-b3cc8ee1144d/children"}},"component_products":{"data":[],"links":{"self":"/products/571e366f-17e6-4e51-8239-b3cc8ee1144d/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/571e366f-17e6-4e51-8239-b3cc8ee1144d/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/571e366f-17e6-4e51-8239-b3cc8ee1144d/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/571e366f-17e6-4e51-8239-b3cc8ee1144d/relationships/variations"}}},"meta":{"created_at":"2024-01-05T10:29:44.214Z","owner":"store","product_types":["parent"],"updated_at":"2024-01-05T10:29:45.212Z","variation_matrix":{"46fff1c9-668b-461a-9344-e7a8cbbbf931":"4d32b816-4397-4a71-b875-4e4ea3ce6745","843868fc-2440-44d1-8ce7-dc474f79ad1c":"cf501150-f02d-49ad-b7d7-33ed15417b76"},"variations":[{"id":"ec2bcebd-f42e-4725-8715-c338589e33ea","name":"Paint colour","options":[{"id":"843868fc-2440-44d1-8ce7-dc474f79ad1c","name":"Blue","description":"This is a colour."},{"id":"46fff1c9-668b-461a-9344-e7a8cbbbf931","name":"Red","description":"This is a colour."}]}]}}}},"get-product-component-child":{"summary":"Child Product","value":{"data":{"type":"product","id":"4d32b816-4397-4a71-b875-4e4ea3ce6745","attributes":{"commodity_type":"physical","name":"Jeans","sku":"jeansRed","slug":"jeansRed","status":"live"},"relationships":{"base_product":{"data":{"type":"product","id":"571e366f-17e6-4e51-8239-b3cc8ee1144d"}},"children":{"data":[]},"component_products":{"data":[],"links":{"self":"/products/4d32b816-4397-4a71-b875-4e4ea3ce6745/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/4d32b816-4397-4a71-b875-4e4ea3ce6745/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/4d32b816-4397-4a71-b875-4e4ea3ce6745/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/4d32b816-4397-4a71-b875-4e4ea3ce6745/relationships/variations"}}},"meta":{"created_at":"2024-01-05T10:29:44.603Z","owner":"store","product_types":["child"],"updated_at":"2024-01-05T10:29:45.155Z","variation_matrix":{},"child_variations":[{"id":"119b2b76-0014-4077-826e-ae80ff207393","name":"Size","options":null,"option":{"id":"fad253ad-4485-4b35-8e3b-b475ad28e78d","name":"Medium","description":"Medium"}},{"id":"10ceafef-7ac9-4352-9797-4825a1671482","name":"Colour","options":null,"option":{"id":"b8128e51-1b0a-4b16-9eda-bb783b17026b","name":"Red","description":"#EE2238"}}]}}}},"get-product-component-products":{"summary":"Component Product","value":{"data":{"type":"product","id":"4ca7de77-994d-4e7c-b834-4cb2ae156f57","attributes":{"commodity_type":"physical","components":{"Apples":{"name":"Apples","options":[{"id":"f809fe4f-83f7-4db4-8175-e467a0d1974a","type":"product","quantity":12}]},"Oranges":{"name":"Oranges","options":[{"id":"7f8f596a-2dc0-4e78-ba0d-3810eac6f86a","type":"product","quantity":12}]}},"description":"fruit","name":"fruit Bundle","slug":"45-b","status":"live"},"relationships":{"children":{"data":[],"links":{"self":"/products/4ca7de77-994d-4e7c-b834-4cb2ae156f57/children"}},"component_products":{"data":[],"links":{"self":"/products/4ca7de77-994d-4e7c-b834-4cb2ae156f57/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/4ca7de77-994d-4e7c-b834-4cb2ae156f57/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/4ca7de77-994d-4e7c-b834-4cb2ae156f57/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/4ca7de77-994d-4e7c-b834-4cb2ae156f57/relationships/variations"}}},"meta":{"created_at":"2022-02-01T12:51:51.132Z","owner":"store","product_types":["bundle"],"updated_at":"2022-02-01T12:51:51.132Z","variation_matrix":{}}},"included":{"component_products":[{"type":"product","id":"f809fe4f-83f7-4db4-8175-e467a0d1974a","attributes":{"commodity_type":"physical","description":"fruit","name":"Apples","sku":"45","status":"live"},"relationships":{"children":{"data":[],"links":{"self":"/products/f809fe4f-83f7-4db4-8175-e467a0d1974a/children"}},"component_products":{"data":[],"links":{"self":"/products/f809fe4f-83f7-4db4-8175-e467a0d1974a/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/f809fe4f-83f7-4db4-8175-e467a0d1974a/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/f809fe4f-83f7-4db4-8175-e467a0d1974a/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/f809fe4f-83f7-4db4-8175-e467a0d1974a/relationships/variations"}}},"meta":{"created_at":"2022-02-01T12:50:33.347Z","owner":"store","product_types":["standard"],"updated_at":"2022-02-01T12:50:33.347Z","variation_matrix":{}}},{"type":"product","id":"7f8f596a-2dc0-4e78-ba0d-3810eac6f86a","attributes":{"commodity_type":"physical","description":"fruit","name":"Oranges","sku":"46","status":"live"},"relationships":{"children":{"data":[],"links":{"self":"/products/7f8f596a-2dc0-4e78-ba0d-3810eac6f86a/children"}},"component_products":{"data":[],"links":{"self":"/products/7f8f596a-2dc0-4e78-ba0d-3810eac6f86a/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/7f8f596a-2dc0-4e78-ba0d-3810eac6f86a/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/7f8f596a-2dc0-4e78-ba0d-3810eac6f86a/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/7f8f596a-2dc0-4e78-ba0d-3810eac6f86a/relationships/variations"}}},"meta":{"created_at":"2022-02-01T12:49:19.298Z","owner":"store","product_types":["standard"],"updated_at":"2022-02-01T12:49:19.298Z","variation_matrix":{}}}]}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a product's nodes

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a product's nodes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/nodes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the nodes associated with the product. Products must be in a `live` status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}},{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the product's nodes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"description":"An array of nodes.","type":"array","items":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"}},"title":"multi_nodes"},"examples":{"get-product-nodes":{"value":{"data":[{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","type":"node","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}},{"type":"node","id":"b2f5e53e-de3c-4548-98da-120f8b185d34","attributes":{"description":"All Dress Shoes","locales":{"fr-FR":{"name":"Chaussures habillées","description":"Toutes les chaussures habillées"}},"name":"Dress Shoes","slug":"dress-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/b2f5e53e-de3c-4548-98da-120f8b185d34/products"}}},"meta":{"created_at":"2024-01-11T19:50:21.729Z","owner":"store","sort_order":3,"updated_at":"2024-01-11T19:50:21.729Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"b2f5e53e-de3c-4548-98da-120f8b185d34","name":"Dress Shoes","slug":"dress-shoes","locales":{"fr-FR":{"name":"Node 2 in French"}}}]}}],"meta":{"results":{"total":2}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Related Product IDs of a Products' attached Custom Relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Related Product IDs of a Products' attached Custom Relationship"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/custom-relationships/{customRelationshipSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

### Prerequisites
  - Relationships have been created between Products, see [Create a Relationship between a product with one or more products](/docs/api/pxm/products/product-association-id).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}},{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."},{"name":"customRelationshipSlug","in":"path","schema":{"type":"string","example":"CRP_electric_devices_2024"},"required":true,"description":"A custom relationship slug."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all related product ids.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"description":"A unique identifier generated when a product relationship is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","properties":{"sort_order":{"description":"The order in which the product to product should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5}}}}}}},"title":"product_association_list_product_ids_response"},"examples":{"list-product-association-product-ids":{"value":{"data":[{"id":"68c48149-0e94-4ef2-93d5-8d5f3774980a","type":"product","attributes":{"sort_order":5}},{"id":"ab4826d1-4a5a-4951-a2a5-98058899f891","type":"product"}]}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Related Products of a Products' attached Custom Relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Related Products of a Products' attached Custom Relationship"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/custom-relationships/{customRelationshipSlug}/products"}
  context={"endpoint"}
>
  
</MethodEndpoint>

### Prerequisites
  - Relationships have been created between Products, see [Create a Relationship between a product with one or more products](/docs/api/pxm/products/product-association-id).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}},{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."},{"name":"customRelationshipSlug","in":"path","schema":{"type":"string","example":"CRP_electric_devices_2024"},"required":true,"description":"A custom relationship slug."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns all related products.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included_response"},"links":{"type":"object","description":"Links allow you to navigate between pages of results.\n\n:::caution Planned pagination changes — on or after 1 September 2026\n\nThe pagination behaviour of PIM list endpoints (for example, `GET /pcm/products` and `GET /pcm/hierarchies`) currently differs from the rest of the Elastic Path Commerce Cloud platform. We plan to align PIM pagination with the platform standard on or after **1 September 2026**. Please review the details below and check that your integration code will handle the new behaviour correctly.\n\n:::\n\n#### Current behaviour\n\nThe current pagination link behaviour in PIM has the following known issues:\n\n- The `current` link is **not returned**.\n- The `first` and `last` links are **not always returned**.\n- The `prev` link is omitted on both the first **and** second pages. It should only be omitted on the first page.\n- The `next` link is omitted on both the last **and** second-to-last pages. It should only be omitted on the last page.\n\n#### Planned behaviour (on or after 1 September 2026)\n\nOn or after 1 September 2026, PIM list endpoints will adopt the following pagination link behaviour, aligning with the rest of the platform:\n\n- `current` — always present, pointing to the current page.\n- `first` — always present.\n- `last` — present on all pages **except the final page**. Omitting `last` on the final page is intentional, to avoid triggering infinite‑loop bugs in integration code that uses the presence of `last` to detect whether more pages remain.\n- `next` — present on all pages except the last page.\n- `prev` — present on all pages except the first page.\n","properties":{"current":{"description":"A link to the current page of results. **Note:** this link is not currently returned by PIM endpoints. It will be introduced on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"first":{"description":"A link to the first page of results. Currently this may not always be present. After the planned changes it will always be present.\n","type":"string","example":"/pcm/hierarchies?page[offset]=0&page[limit]=10"},"last":{"description":"A link to the last page of results. Currently this may not always be present. After the planned changes it will be present on all pages except the final page (where it is intentionally omitted).\n","type":"string","example":"/pcm/hierarchies?page[offset]=20&page[limit]=10"},"next":{"description":"A link to the next page of results. Should be absent on the last page. Currently this is incorrectly absent on the second-to-last page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=10&page[limit]=10"},"prev":{"description":"A link to the previous page of results. Should be absent on the first page. Currently this is incorrectly absent on the second page as well; this will be fixed on or after 1 September 2026.\n","type":"string","example":"/pcm/hierarchies?page[offset]=8&page[limit]=10"}},"title":"multi_links"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}},"title":"multi_product_response"},"examples":{"list-products":{"value":{"data":[{"type":"product","id":"9c85b276-09b4-488e-a59c-c561bae14c9e","attributes":{"commodity_type":"physical","custom_inputs":{"back":{"name":"T-Shirt Back","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false},"front":{"name":"T-Shirt Front","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false}},"description":"T-shirt.","mpn":"1234-5678-TTTT","name":"T-Shirt","sku":"97805","slug":"97805","status":"live","upc_ean":"12345656","tags":["tag1","tag2"],"extensions":{"products(size)":{"widthMM":600,"fuelType":"electric","hasUKPlug":true,"online":null}}},"relationships":{"children":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/children"}},"component_products":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/9c85b276-09b4-488e-a59c-c561bae14c9e/relationships/variations"}}},"meta":{"created_at":"2022-08-18T14:25:57.391Z","owner":"store","product_types":["standard"],"updated_at":"2022-08-18T14:25:57.391Z"}}],"meta":{"results":{"total":1}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a variation option

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a variation option"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/variations/{variationID}/options/{optionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a variation option

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"optionID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the option."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the variation option.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier generated when an option is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation-option`.","type":"string","enum":["product-variation-option"]},"attributes":{"type":"object","description":"A variation option represents an option for selection for a single product-variation. For example, if your variation is `color`, you might have three possible options; red, green, and blue.","additionalProperties":false,"properties":{"name":{"description":"A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string"},"description":{"description":"A human-recognizable description for the option.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"}}},"meta":{"type":"object","properties":{"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["organization","store"]},"created_at":{"type":"string","description":"The date and time an option is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time an option is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"modifiers":{"type":"array","description":"The modifiers associated with this option.","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier generated when a modifier is created."},"type":{"type":"string","description":"The type of modifier.","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"type":"string","nullable":true,"description":"Required for non-builder modifiers. The value of the modifier type."},"seek":{"type":"string","nullable":true,"description":"Required for builder modifiers. The sub-string to find and replace."},"set":{"type":"string","nullable":true,"description":"Required for builder modifiers. The value to replace matches of the seek string."},"owner":{"type":"string","nullable":true,"description":"The owner of the modifier, either `organization` or `store`.","enum":["organization","store"]}}}}}}}}},"title":"single_option"},"examples":{"get-variation-option":{"value":{"data":{"type":"product-variation-option","id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","attributes":{"description":"Our most popular color","name":"Blue","sort_order":0},"meta":{"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a variation

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a variation"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/variations/{variationID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a variation

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns the specified variation.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier for a variation.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation`.","type":"string","enum":["product-variation"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The name for a variation.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"}}},"meta":{"type":"object","properties":{"options":{"description":"A variation option represents an option for selection for a single product-variation. For example, if your variation is `color`, you might have three possible options; red, green, and blue.","type":"array","items":{"type":"object","description":"The options available for this variation","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed."},"description":{"type":"string","description":"A description for an option."},"created_at":{"type":"string","description":"The date and time an option is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time an option is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"modifiers":{"type":"array","description":"The modifiers associated with this option.","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier generated when a modifier is created."},"type":{"type":"string","description":"The type of modifier.","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"type":"string","nullable":true,"description":"Required for non-builder modifiers. The value of the modifier type."},"seek":{"type":"string","nullable":true,"description":"Required for builder modifiers. The sub-string to find and replace."},"set":{"type":"string","nullable":true,"description":"Required for builder modifiers. The value to replace matches of the seek string."},"owner":{"type":"string","nullable":true,"description":"The owner of the modifier, either `organization` or `store`.","enum":["organization","store"]}}}}}}},"owner":{"description":"The owner of the resource, either `organization` or `store`.","type":"string","enum":["organization","store"]},"created_at":{"type":"string","description":"The date and time a variation is created."},"updated_at":{"type":"string","description":"The date and time a variation is updated."}}}}}},"title":"single_variation"},"examples":{"get-variation":{"value":{"data":{"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"product-variation","attributes":{"name":"Paint Color","sort_order":1},"meta":{"options":[{"id":"3de2c96c-2a99-4ded-bcf8-eeba32c0c5be","name":"Red","description":"Red color","sort_order":2,"created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"},{"id":"31f2d09b-8a10-447a-b3ad-3358d07f818a","name":"Blue","description":"Blue color","sort_order":1,"created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}],"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Hierarchies

```mdx-code-block
import HierarchyOverview from '/docs/partials/pxm/hierarchies/hierarchies.mdx';
import HierarchyCatalog from '/docs/partials/pxm/hierarchies/hierarchycatalogs.mdx';

<HierarchyOverview />

## Creating Hierarchies and Nodes

You can create the **Major Appliances** hierarchy by performing the following steps.

1. Using [**Create a Hierarchy**](/docs/api/pxm/products/create-hierarchy), create a hierarchy whose name is **Major Appliances**. Each hierarchy has a hierarchy ID. In other words, the hierarchy ID is the ID of the root node.
1. Using [**Create a Node in a hierarchy**](/docs/api/pxm/products/create-node), create the following child nodes. When you create a node in a hierarchy, by default, the node is a child of the root node. Specify `sort_order` to configure the order of the nodes.
   - **Ranges**
   - **Refrigerators**
   - **Dishwashers**
1. Using [**Create a Node in a hierarchy**](/docs/api/pxm/products/create-node), create the **Electric Ranges** node, specifying **Ranges** as the parent node.
1. Using [**Create a Node in a hierarchy**](/docs/api/pxm/products/create-node), create the following nodes, specifying **Electric Ranges** as the parent node.
   - **Electric Ranges 24ˮ**
   - **Electric Ranges 30ˮ**
   - **Double Oven**
1. Using [**Create a Node in a hierarchy**](/docs/api/pxm/products/create-node), create the **Gas Ranges** node, specifying **Ranges** as the parent node.
1. Using [**Create a Node in a hierarchy**](/docs/api/pxm/products/create-node), create the following nodes, specifying **Gas Ranges** as the parent node.
   - **Gas Ranges 24ˮ**
   - **Gas Ranges 30ˮ**
   - **Gas Ranges 32"**
   - **Double Oven**
1. Using [**Create a Node in a hierarchy**](/docs/api/pxm/products/create-node), create the following nodes, specifying **Dishwashers** as the parent node.
    - **Built-in**
    - **Standalone**

## Hierarchies and Catalogs

<HierarchyCatalog />

```

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Import Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Import Products"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/import"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can use the Product Import API to:

- Add new products, including:

    - main image files. See [Importing Main Image Files](/docs/api/pxm/products/product-import-bulk-update#using-imported-main-image-files).
    - custom data. See [Importing custom data](/docs/api/pxm/products/product-import-bulk-update#importing-custom-data-flows).
    - Make bulk updates to existing products.

You cannot use product import to:

- Delete existing products.
- Import product bundles.

The Product Import API uses a Comma Separated Values (CSV) file to import products, main image files, custom extension data, and admin and shopper attributes. Each row in a .csv file represents a product you want to create/update. See an [example file](/assets/pim_product_import_example.csv).

Each file can have 50,000 rows, including the header. If a CSV file exceeds 50,000 rows, an error is displayed, and the products are not imported. A CSV file must not be larger than 50 megabytes. If a CSV file is larger than 50 megabytes, a `503 client read` error is displayed.

If you want to create/update more than 50,000 products or your CSV file is larger than 50 megabytes, you must have a separate CSV file and import each CSV file one at a time.

See [**Characteristics of CSV Files**](/docs/api/pxm/products/product-import-bulk-update#characteristics-of-csv-import-files).

## Custom Attributes in CSV

You can set custom attributes on products using CSV columns with the prefixes `shopper_attributes.` or `admin_attributes.` followed by the attribute key name. For example:

- `shopper_attributes.color` sets the `color` key on `shopper_attributes`.
- `admin_attributes.cost_of_goods` sets the `cost_of_goods` key on `admin_attributes`.

**Partial updates:** When updating an existing product, only the attribute keys present as columns in the CSV are affected. Attribute keys not included as columns are left unchanged.

**Removing an attribute key:** To explicitly delete an attribute key from an existing product, set the cell value to `__REMOVE_ATTRIBUTE__`. This special sentinel value instructs the importer to remove that key from the product's custom attributes. An empty cell value is treated as a literal empty string, not a deletion.

**New products:** For new products being created via import, any column whose value is `__REMOVE_ATTRIBUTE__` is ignored (the key is not created).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"locale","in":"query","description":"Specifies the locale to assist in parsing flow entry date values.\n\n- If a supported locale is provided, the system attempts to interpret dates using that locale's conventions. The import job fails if a date does not match one of the supported locale's formats.\n- If this parameter is omitted, or if the value provided is not on the supported list, the system proceeds using its default parsing logic. An unsupported locale is ignored and does not cause a failure.\n\n**Supported Locales and Date Formats:**\n\n**`en-US`**\n- `1/2/2006 15:04:05`\n- `01/02/2006 15:04:05`\n- `1/2/06 15:04`\n\n**`en-GB`**\n- `2/1/2006 15:04:05`\n- `02/01/2006 15:04:05`\n- `2/1/06 15:04`\n\n**`en-CA`**\n- `2/1/2006 15:04:05`\n- `02/01/2006 15:04:05`\n- `2/1/06 15:04`     \n\nAdditional locales and date formats can be added upon request.\n","required":false,"schema":{"type":"string","enum":["en-US","en-GB","en-CA"]},"example":"en-US"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"description":"The file you want to upload. Ensure that the file format is Comma Separated Values (CSV).","type":"string","format":"binary","example":"UploadFile"}}},"examples":{"upload_image":{"summary":"Upload Image","value":{"file":"@path/to/file"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Import started","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a job is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `pim-job`.","type":"string","enum":["pim-job"]},"attributes":{"type":"object","required":["started_at","completed_at","created_at","updated_at","type","status"],"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true},"completed_at":{"type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time","nullable":true,"description":"The date and time a job is completed."},"created_at":{"type":"string","description":"The date and time a job is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time a job is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"type":{"type":"string","description":"The status of a job.\n\n* `pending` - Commerce has received the request but is currently busy processing other requests.\n* `started` - Commerce has started processing the job.\n* `success` - The job has successfully completed.\n* `failed` - The job has failed.\n","enum":["child-products","product-import","product-export","hierarchy-duplicate","pricebook-import","pricebook-delete","hierarchy-delete","indexing-job","attach-nodes"]},"status":{"type":"string","enum":["pending","cancelled","cancelling","started","success","failed"]}}},"meta":{"type":"object","required":["x_request_id"],"properties":{"x_request_id":{"type":"string","description":"Applies to all job types. A unique request ID is generated when a job is created."},"copied_from":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The ID of the original hierarchy that you duplicated."},"hierarchy_id":{"type":"string","description":"Applies to `hierarchy-duplicate` job types. The duplicated hierarchy ID."},"file_locations":{"type":"array","nullable":true,"description":"If the job type is `product_export`, a link to the file is created when running a job.","items":{"type":"string"}},"filter":{"type":"string","nullable":true,"description":"The entities included in the job. For example, if the job type is `product-export`, the PXM products included in the export."}}}},"title":"job"}},"title":"single"},"examples":{"pending":{"summary":"Successful Job","value":{"data":{"type":"pim-job","id":"7e1b9ba1-c844-4556-9b16-4ae3f0988b0f","attributes":{"completed_at":null,"created_at":"2024-01-05T15:27:23.161Z","started_at":null,"status":"pending","type":"product-import","updated_at":"2024-01-05T15:27:23.161Z"},"meta":{"x_request_id":"fad8c5c0-9546-4e0c-b68e-8a2d809891e5"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Jobs(Products)

```mdx-code-block
import ProductJobs from '/docs/partials/pxm/jobs/jobs.mdx';

<ProductJobs />
```

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Get all Custom Relationships attached to a Product

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Custom Relationships attached to a Product"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/pcm/products/{productID}/custom-relationships"}
  context={"endpoint"}
>
  
</MethodEndpoint>

### Prerequisites
  - Custom Relationships have been attached to a product, see [Attach Custom Relationships to a Product](/docs/api/pxm/products/attach-custom-relationships)
  - **OR** Products have been related to one another, see [Create a Relationship between a product with one or more products](/docs/api/pxm/products/product-association-id)

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":0}},{"name":"page[limit]","in":"query","description":"The number of records per page. The maximum limit is 100.","schema":{"type":"integer","minimum":0,"maximum":10000,"format":"int64","example":10}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","type"],"properties":{"slug":{"type":"string","description":"The slug of the custom relationship."},"type":{"type":"string","enum":["custom-relationship"],"description":"This represents the type of resource. Always `custom-relationship`."}}}}},"title":"attach_custom_relationship_request"},"examples":{"assign-custom-relationship-to-product":{"value":{"data":[{"type":"custom-relationship","slug":"CRP_related_products"},{"type":"custom-relationship","slug":"CRP_cart_products"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns the attached custom relationship.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a custom relationship is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `custom-relationship`.","type":"string","enum":["custom-relationship"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"description":"The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.","type":"string","example":"Related Products"},"description":{"description":"A description of the custom relationship.","type":"string","example":"A list of related products shown on the PDP."},"slug":{"description":"A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string","example":"CRP_related_products","pattern":"^[A-Za-z0-9._-]+$"},"sort_order":{"description":"The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5},"external_name":{"description":"The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.","nullable":true,"type":"string","example":"Similar items to consider"},"external_description":{"description":"The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.","nullable":true,"type":"string","example":"Check out these similar products that may also meet your needs or match your preferences."},"bi_directional":{"type":"boolean","description":"Is this relationship one way or bi-directional `true` or `false`. Default is false","default":false}},"title":"req_attributes_custom_relationship"},"meta":{"type":"object","required":["owner","timestamps"],"properties":{"owner":{"description":"The owner of the resource.","type":"string","example":"store"},"timestamps":{"type":"object","required":["created_at","updated_at"],"properties":{"created_at":{"description":"The date and time the resource is created.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"},"updated_at":{"description":"The date and time the resource is updated.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"}}}}}},"title":"custom_relationship"}},"links":{"type":"object","description":"Links are used to allow you to move between requests.","properties":{"first":{"description":"Always the first page.","type":"string","example":"/pcm/custom_relationships?page[offset]=0&page[limit]=10"},"last":{"description":"This is `null` if there is only one page.","type":"string","example":"/pcm/custom_relationships?page[offset]=20&page[limit]=10"},"next":{"description":"This is `null` if there is only one page.","type":"string","example":"/pcm/custom_relationships?page[offset]=10&page[limit]=10"},"prev":{"description":"This is `null` if you on the first page.","type":"string","example":"/pcm/custom_relationships?page[offset]=8&page[limit]=10"}},"title":"multi_links_cr"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":30,"minimum":0}}}},"title":"multi_meta"}},"title":"multi_custom_relationships"},"examples":{"custom-relationship":{"value":{"data":[{"id":"f3297ee8-da90-45e9-ae56-a2654aebbdfe","type":"custom-relationship","attributes":{"name":"Kitchen electrics","description":"Kitchen electric devices","slug":"CRP_kitchen_individual_devices","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}},{"id":"21b1315b-c47f-4766-85bf-7bf0f94d73b6","type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","bi_directional":true},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}},{"id":"e390ff7e-efc4-4769-90d2-fceabcc1e2cd","type":"custom-relationship","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","sort_order":5,"external_name":"Similar items to consider","external_description":"Check out these similar products that may also meet your needs or match your preferences.","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}}],"links":{"last":"/pcm/custom_relationships?page[offset]=29&page[limit]=1","next":"/pcm/custom_relationships?page[offset]=1&page[limit]=1"},"meta":{"results":{"total":3}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Relationship between a Product with one or more Products

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Relationship between a Product with one or more Products"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/pcm/products/{productID}/custom-relationships/{customRelationshipSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

- You can associate a product with up to 2000 other products. 
- You do not need to attach a custom relationship to products beforehand, this will be done automatically by this endpoint. 
- This is a partial update, so if you make a request to this endpoint multiple times with different products in each request, they will not be overwritten but will be appended to the related products list. 

If you want to remove a relationship between products, see [Delete a Relationship between a product with one or more products](/docs/api/pxm/products/dissociate-products).  

 ### Prerequisites
   - A Custom Relationship has been created, see [create a Custom Relationship](/docs/api/pxm/products/create-custom-relationship).
   - A Product has been created for the relationship to be based from.
   - One or many Product have been created for the product to relate to.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."},{"name":"customRelationshipSlug","in":"path","schema":{"type":"string","example":"CRP_electric_devices_2024"},"required":true,"description":"A custom relationship slug."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The ID of the product you want to relate."},"type":{"type":"string","enum":["product"],"description":"This represents the type of resource being returned. Always `product`."},"attributes":{"type":"object","properties":{"sort_order":{"description":"The order in which the product to product should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5}}}}}}},"title":"product_association_request"},"examples":{"create-product-association":{"value":{"data":[{"type":"product","id":"68c48149-0e94-4ef2-93d5-8d5f3774980a","attributes":{"sort_order":5}},{"type":"product","id":"ab4826d1-4a5a-4951-a2a5-98058899f891"},{"type":"product","id":"97b7fac2-91dd-4755-81b0-bdffe8e7eabd"},{"type":"product","id":"a0ef3291-2ec1-4d7d-9d6d-1705ae01bb99","attributes":{"sort_order":2}},{"type":"product","id":"bde79675-4783-40b7-8a7e-ac6df41459c6"},{"type":"product","id":"aaddd5f4-a5f8-42e8-be9a-097986f22e58"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Returns information related to associated products.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"associated_products":{"description":"A list of product IDs that have been successfully associated with this custom relationship.","type":"array","items":{"type":"string"},"example":["68c48149-0e94-4ef2-93d5-8d5f3774980a","ab4826d1-4a5a-4951-a2a5-98058899f891"]},"products_not_associated":{"description":"A list of products that could not be associated, including the reasons why.","type":"array","items":{"type":"object","properties":{"ID":{"description":"The ID of the product that could not be associated.","type":"string","example":"97b7fac2-91dd-4755-81b0-bdffe8e7eabd"},"Details":{"description":"Details about why the product could not be associated.","type":"string","example":"could not find product"}}},"example":[{"ID":"97b7fac2-91dd-4755-81b0-bdffe8e7eabd","Details":"could not find product"},{"ID":"a0ef3291-2ec1-4d7d-9d6d-1705ae01bb99","Details":"product already has 5 custom relationships, cannot associate more as it has reached the limit of 5 custom relationships"},{"ID":"bde79675-4783-40b7-8a7e-ac6df41459c6","Details":"product already has 5 custom relationships, cannot associate more as it has reached the limit of 5 custom relationships"},{"ID":"aaddd5f4-a5f8-42e8-be9a-097986f22e58","Details":"exceeded maximum allowed associations (2000). Please review and try again"}]},"owner":{"description":"The owner of the resource.","type":"string","example":"store"},"timestamps":{"type":"object","properties":{"created_at":{"description":"The date and time the resource was created.","type":"string","example":"2024-08-08T09:29:08.295Z","format":"date-time"},"updated_at":{"description":"The date and time the resource was last updated.","type":"string","example":"2024-08-08T09:29:08.295Z","format":"date-time"}}}}}},"title":"product_association_response"},"examples":{"create-product-association":{"value":{"meta":{"associated_products":["68c48149-0e94-4ef2-93d5-8d5f3774980a","ab4826d1-4a5a-4951-a2a5-98058899f891"],"products_not_associated":[{"ID":"97b7fac2-91dd-4755-81b0-bdffe8e7eabd","Details":"could not find product"},{"ID":"a0ef3291-2ec1-4d7d-9d6d-1705ae01bb99","Details":"product already has 5 custom relationships, cannot associate more as it has reached the limit of 5 custom relationships"},{"ID":"bde79675-4783-40b7-8a7e-ac6df41459c6","Details":"product already has 5 custom relationships, cannot associate more as it has reached the limit of 5 custom relationships"},{"ID":"aaddd5f4-a5f8-42e8-be9a-097986f22e58","Details":"product exceeds the maximum limit of associated products (2000). Please review and try again"}],"owner":"store","timestamps":{"created_at":"2024-08-08T09:29:08.295Z","updated_at":"2024-08-08T09:29:08.295Z"}}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Product Experience Manager Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/pim/pim.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Product Experience Manager Introduction"}
>
</Heading>

Product Experience Manager uses the PIM service to manage product information, hierarchies, and price books. Ideally, Product Experience Manager becomes the single source of truth for product data across your organization.

In Commerce, the product data is stored separately from pricing, catalogs, and inventory. This separation means that you retrieve all product data only when you are managing product data and assets. Otherwise, when setting prices or managing inventory, you retrieve a reference to the product rather than the entire product, which makes the response times very fast.

You also have the flexibility to create catalogs for different scenarios by combining hierarchies of products with a price book. Scenarios might include:

- **Multiple geographical regions**. Display different catalogs in different regions with suitable pricing or combine product hierarchies from two different regions to display in a third region.
- **Multiple channels**. Display different catalogs based on how a shopper accesses your store, such as through a mobile app or a web storefront.
- **Direct to business versus direct to customers**. Offer different products and prices for business customers versus retail customers.
- **Preferred customers**. Offer special pricing to preferred customers while displaying a standard price catalog to all other shoppers.
- **Reward programs**. Enable reward programs where catalog prices drop after a certain spending level is reached.
- **Product sales**. Offer sale items for a limited time.

Scenarios are created by defining the context within which a catalog is displays. Contexts can be a customer ID, a channel, or any other user-defined tag that can be passed to the APIs from the front-end shopper experiences.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"bearerAuth"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Product Export

```mdx-code-block
import ProductExport from '/docs/partials/pxm/import/export.mdx';

<ProductExport />
```

### Characteristics of Exporting Products

- Product exports are an asynchronous operation. When you send a request to the Export API, it triggers an asynchronous job to build the `.csv` file containing the product entries.
- Jobs are processed one at a time. You can continue to send product export requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See [**Jobs**](/docs/api/pxm/products/jobs).
- The Export API response includes a job resource. In the response, you can verify the job status; if the status is successful, the response includes a link to the location where the `.csv` file is stored. See [**Product Export CSV File**](#product-export-csv-file). A single CSV file contains 10,000 rows, excluding the header. If you are exporting 50,000 products, the job endpoint response contains links to five `.csv` files; each `.csv` file including 10,000 products.
- You might have specified custom extension data in a `.csv` file when you imported the products. These modifications are all exported. So, when you send a request to the Export API, the `.csv` file, included in the Job endpoint response, reflects any changes that you have made.
- You cannot export product bundles.

### Product Export CSV File

The Product Export API generates a Comma Separated Values (CSV) file that you can use to import/update products, main image files, and custom extension data. 

The `.csv` file is:

 - Comma-separated.
 - Header-based.
   - Header attributes must be the same as the product attributes.
   - Header names can be in any order.
 - Each row after the first line represents a single product.

The following table describes the headers that are supported.

| Header                           | Required | Description |                                                             
|:---------------------------------|:---------|:-----------------------------------------------------|
| id                               | Optional | A unique product ID that is generated when you create the product. The `id` is used to look up products in the `.csv` file and matches them to the products in your storefront that you want to update.                                                    |
| external_ref                     | Optional | A unique attribute associated with a product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.  |                                                                                          
| name                             | Required | The name of a product.     |                                                                              
| description                      | Required | A description for a product. You can include quotes in your product description, if you want to emphasize a word, for example. To do this, put quotes around the product description. For example, "This product description describes my "product" and the product "version"." |
| slug                             | Required | A label for the product that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. By default, the product name is used as the slug.                |
| status                           | Required | The status of a product, either `Draft` or `Live`.    |                                                  
| commodity_type                   | Required | The commodity type, either `physical` or `digital`.    |                                                 
| upc_ean                          | Optional | The universal product code or european article number of the product.     |                               
| mpn                              | Optional | The manufacturer part number of a product.       |                                                        
| sku                              | Optional | The unique stock keeping unit of the product.   |   
| tags                             | Optional | The product tags used to store or assign a key word against a product. A product can have up to 20 product tags. A product tag can be up to 255 characters. See [**Product Tags**](/docs/api/pxm/products/product-tags
).                                                   |
| main_image_id                    | Optional | Specifies a unique ID of a main image file for a product. See [Exporting Main Image Files](#exporting-main-image-files).  |                                                                                                                       
| `_created_at`                      | Optional| The date and time a product was created. **Note**: This field does not populate any data; it is provided solely for informational purposes.      |                                                                                                               
| `_updated_at`                      | Optional | The date and time a product was updated. **Note**: This field does not populate any data; it is provided solely for informational purposes.        |                                                                                                             
| `template:<templateID>:created_at` | Optional | The date and time a template was created. **Note**: This field does not populate any data; it is provided solely for informational purposes.         |                                                                                                           
| `template:<templateID>:updated_at` | Optional | The date and time a template was updated. **Note**: This field does not populate any data; it is provided solely for informational purposes.      |                                                                                                              
| `template:<flowID>:<fieldName>`  | Optional | Custom extension data includes the flow `ID` or `slug` and the field `name`. See [Exporting Custom Data (Flows)](#exporting-custom-data-flows).   |                                                                                                              

### Exporting Main Image Files

The main images that you have previously uploaded Commerce are exported. A `main_image_id` header is added to your `.csv` file. The ID in `main_image_id` is the ID of a file that has already been uploaded to Commerce using [create a file](/docs/api/pxm/files/create-a-file).

### Exporting Custom Data (Flows)

Custom extension data is exported in a `.csv` file by creating a header that includes the flow `ID` or `slug` and the field `name` as shown below:

- `template:<flowSlug>:<fieldName>`
- `template:<flowID>:<fieldName>`

where:

- `template` must be `template`.
- one of the following for the template that contains the field whose data you want to export:
  - `flowID` is the ID of the flow.
  - `flowSlug` is the flow slug.
- `fieldName` is the name of the field whose data you want to export.

In the following example, for a flow with ID `82c10a02-1851-4992-8ecb-d44f2782d09b` and a field with the name `condition`:

- the header is `template:82c10a02-1851-4992-8ecb-d44f2782d09b:condition`.
- the updated custom data is `as-new`.

| name | slug | sku | status | template:82c10a02-1851-4992-8ecb-d44f2782d09b:condition |
| :--- | :--- | :--- | :--- | :--- |
| BestEver Range | bestever-range-1a1a-30 | BE-Range-1a1a-30 | draft | as-new |

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Product File Relationships

Products are the items or services that you might want to sell in your store. In Product Experience Manager, products can also have associated rich media assets, such as product images or a file containing additional product details.

You can do this using [Files API](/docs/api/pxm/files).

Once you have created your files, you associate files with your products using the [Create Product-File Relationships API](/docs/api/pxm/products/create-product-file-relationships).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Product Image Relationships

Products are the items or services that you might want to sell in your store. In Product Experience Manager, products can also have associated rich media assets, such as product images or a file containing additional product details.

You can do this using [Files API](/docs/api/pxm/files).

Once you have created your files, you associate files with your products using the [Create Product Main Image Relationships API](/docs/api/pxm/products/create-product-main-image-relationships).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Product Import/Bulk Update

```mdx-code-block
import ProductImport from '/docs/partials/pxm/import/import.mdx';

<ProductImport />
```

#### Using Imported Main Image Files

You can use the main images that you have previously uploaded to Commerce and assign them to your products when importing products to Commerce. You can do this by adding a `main_image_id` header to your `.csv` file. The ID you provide in `main_image_id` is the ID of a file that has already been uploaded to Commerce using create a file.

#### Importing Custom Data (Flows)

You can also create/update custom extension data in a `.csv` file by creating a header that includes the flow `ID` and the field `slug` in the following format: 

template:*flowID*:*fieldSlug*.

where:

- `template` must be `template`.
- `flowID` is the ID of the flow that contains the field whose data you want to create/update.
- `fieldSlug` is the slug of the field whose data you want to create/update.

In the following example, for a flow with ID `82c10a02-1851-4992-8ecb-d44f2782d09b` and a field with the slug `condition`:

- the header is `template:82c10a02-1851-4992-8ecb-d44f2782d09b:condition`.
- the updated custom data is `as-new`.

    | name | slug | sku | status | template:82c10a02-1851-4992-8ecb-d44f2782d09b:condition |
    | :--- | :--- | :--- | :--- | :--- |
    | BestEver Range | bestever-range-1a1a-30 | BE-Range-1a1a-30 | draft | as-new |

#### Characteristics of CSV Import Files

Product Import uses a [**Comma Separated Values (CSV)**](#characteristics-of-csv-import-files) file to import/update products, main image files, and custom extension data. 

- Each row in a `.csv` file represents a product you want to create/update. 
- Each file:
    - must not be larger than 50 megabytes. If a `.csv` file is larger than 50 megabytes, a `503 client read error` is displayed.
    - must not have more than 50,000 rows, including the header. If a CSV file exceeds 50,000 rows, an error is displayed, and the products are not imported.
    In other words, if you have a file with 50,000 rows that is larger than 50 megabytes, an error is displayed, and the products are not imported.
- If you want to create/update more than 50,000 products or your `.csv` file is larger than 50 megabytes, you must have a separate `.csv` file and import each `.csv` file one at a time.
- You can update existing products, including images, templates/flow fields, and entries. The entry in the `.csv` file must have a unique `id` and/or `external_ref` that matches the `id` and `external_ref` of the existing product you want to update. You may have both a unique `id` and `external_ref`, but you must have at least one.
- You can add new products. For new products that you want to add, the entry in the `.csv` file must have an `external_ref` that does not match any existing products.

The following table describes the headers that are supported.

| Header | Required | Description  |
|:---- |:---------|:--|
| id                              | Optional | A unique product ID that is generated when you create the product. The `id` is used to look up products in the `.csv` file and matches them to the products in your storefront that you want to update.                                                                                                                                                                                                       |
| external_ref                    | Optional | A unique attribute associated with a product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.                                                                                                                                                                                                                                         |
| name                            | Required | The name of a product.                                                                                                                                                                                                                                                                                                                                                                                        |
| description                     | Required | A description for a product. You can include quotes in your product description, if you want to emphasize a word, for example. To do this, put quotes around the product description. For example, "This product description describes my "product" and the product "version"."                                                                                                                               |
| slug                            | Required | A label for the product that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. By default, the product name is used as the slug.                                                                                                                                                                |
| status                          | Required | The status of a product, either `Draft` or `Live`.                                                                                                                                                                                                                                                                                                                                                            |
| commodity_type                  | Required | The commodity type, either `physical` or `digital`.                                                                                                                                                                                                                                                                                                                                                           |
| upc_ean                         | Optional | The universal product code or european article number of the product.                                                                                                                                                                                                                                                                                                                                         |
| mpn                             | Optional | The manufacturer part number of a product.                                                                                                                                                                                                                                                                                                                                                                    |
| sku                             | Optional | The unique stock keeping unit of the product.                                                                                                                                                                                                                                                                                                                                                                 |
| tags                             | Optional | The product tags used to store or assign a key word against a product. A product can have up to 20 product tags. A product tag can be up to 255 characters. See [**Product Tags**](/docs/api/pxm/products/product-tags).
| main_image_id                   | Optional | Specifies a unique ID of a main image file for a product. You can include a `main_image_id` for your products for images that are already uploaded to Commerce. See [**Using Main Image Files**](#importing-custom-data-flows).                                                                                                                                                                                        |
| `template:<flowID>:<fieldSlug>` | Optional | You can also specify custom extension data in the CSV by specifying the flow `ID` or `slug` and the field `name`. For example, `template:<flowSlug>:<fieldName>` format. See [**Importing Custom Data (Flows)**](#importing-custom-data-flows). |

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Product Tags

```mdx-code-block
import ProductTags from '/docs/partials/pxm/products/tags.mdx';

<ProductTags />
```

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Products

```mdx-code-block
import ProductsOverview from '/docs/partials/pxm/products/productsoverview.mdx';
import ProductTypes from '/docs/partials/pxm/products/types.mdx';
import ProductTags from '/docs/partials/pxm/products/tags.mdx';
import PersonalProducts from '/docs/partials/pxm/products/personalizing.mdx';
import ProductCatalogs from '/docs/partials/pxm/products/catalogs.mdx';
import Overview from "/docs/partials/pxm/bundles/bundles.mdx";
import ComponentOptions from "/docs/partials/pxm/bundles/components.mdx";
import BundlePricing from "/docs/partials/pxm/bundles/bundlepricing.mdx";
import DynamicBundles from "/docs/partials/pxm/bundles/dynamic.mdx";
import BundlesBundles from "/docs/partials/pxm/bundles/bundlesof.mdx";

<ProductsOverview />

### Product Types

<ProductTypes />

### Personalizing Products

<PersonalProducts />

### Products and Catalog Releases

<ProductCatalogs />

### Bundles

<Overview></Overview>

### Bundle Components and Options

<ComponentOptions></ComponentOptions>

### Bundle Pricing

<BundlePricing></BundlePricing>

### Dynamic Bundles

<DynamicBundles></DynamicBundles>

#### Creating Dynamic Bundles: An Overview

The following steps are an overview of how to use dynamic bundles.

1. Create your products using [**create a product**](/docs/api/pxm/products/create-product).
1. Create a bundle using [**create a bundle**](/docs/api/pxm/products/create-product).
1. Specify minimum and/or maximum values for the number of product options that can be selected within the bundle. For example, if you want the shopper to select exactly 4 out of 10 options, set both the minimum and maximum values to 4 for each of the 10 product options.
1. For each product option in the bundle, specify if it is a default option by adding `"default": true` to the product options that you want to be pre-selected for the shopper.
1. Publish the bundle to your catalog using the [Publish a catalog](/docs/api/pxm/catalog/publish-release) endpoint so you can display the products to your shoppers in your storefront.
1. When a shopper interacts with the bundle on your storefront, they can select the products they want from the list of options. Use the [configure a shopper bundle](/docs/api/pxm/catalog/configure-by-context-product) endpoint to capture the shoppers selections. This updates the `bundle_configuration` with the product options chosen by a shopper.
1. Once a shopper has configured their bundle, use the add a product to a cart endpoint to add the selected bundle to the shopper’s cart.
1. When the shopper proceeds to checkout, the selected product options from the bundle are included in the order.

### Bundles of Bundles

<BundlesBundles></BundlesBundles>

#### Creating Bundles of Bundles: An Overview

To create a bundle of bundles, simply add a bundle as a component to another bundle.

1. Create your products using [**create a product**](/docs/api/pxm/products/create-product).
1. Create all your child bundles using [**create a bundle**](/docs/api/pxm/products/create-product).
1. [**Create a parent bundle**](/docs/api/pxm/products/create-product) and specify the product ID of your child bundle as an option of a component in your bundle. You cannot have more than 1500 options in a bundle.
```

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Update a custom relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a custom relationship"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/custom-relationships/{customRelationshipSlug}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates a custom relationship. 

A partial update can be performed, where you specify only the fields that need to be changed.

The custom relationship slug cannot be updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"customRelationshipSlug","in":"path","schema":{"type":"string","example":"CRP_electric_devices_2024"},"required":true,"description":"A custom relationship slug."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier of the custom relationship.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource object being returned. Always `custom-relationship`.","type":"string","enum":["custom-relationship"],"example":"custom-relationship"},"attributes":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"description":"The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.","type":"string","example":"Related Products"},"description":{"description":"A description of the custom relationship.","type":"string","example":"A list of related products shown on the PDP."},"slug":{"description":"A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string","example":"CRP_related_products","pattern":"^[A-Za-z0-9._-]+$"},"sort_order":{"description":"The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5},"external_name":{"description":"The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.","nullable":true,"type":"string","example":"Similar items to consider"},"external_description":{"description":"The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.","nullable":true,"type":"string","example":"Check out these similar products that may also meet your needs or match your preferences."},"bi_directional":{"type":"boolean","description":"Is this relationship one way or bi-directional `true` or `false`. Default is false","default":false}},"title":"req_attributes_custom_relationship"}}}},"title":"update_custom_relationship"},"examples":{"update-custom-relationship":{"summary":"Update","value":{"data":{"type":"custom-relationship","id":"f3297ee8-da90-45e9-ae56-a2654aebbdfe","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","sort_order":5,"external_name":"Similar items to consider","external_description":"Check out these similar products that may also meet your needs or match your preferences.","bi_directional":false}}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the updated custom relationship","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier generated when a custom relationship is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `custom-relationship`.","type":"string","enum":["custom-relationship"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"description":"The name of the custom relationship to display to shoppers, such as `Kitchen electrics`.","type":"string","example":"Related Products"},"description":{"description":"A description of the custom relationship.","type":"string","example":"A list of related products shown on the PDP."},"slug":{"description":"A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string","example":"CRP_related_products","pattern":"^[A-Za-z0-9._-]+$"},"sort_order":{"description":"The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.","nullable":true,"type":"integer","example":5},"external_name":{"description":"The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.","nullable":true,"type":"string","example":"Similar items to consider"},"external_description":{"description":"The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.","nullable":true,"type":"string","example":"Check out these similar products that may also meet your needs or match your preferences."},"bi_directional":{"type":"boolean","description":"Is this relationship one way or bi-directional `true` or `false`. Default is false","default":false}},"title":"req_attributes_custom_relationship"},"meta":{"type":"object","required":["owner","timestamps"],"properties":{"owner":{"description":"The owner of the resource.","type":"string","example":"store"},"timestamps":{"type":"object","required":["created_at","updated_at"],"properties":{"created_at":{"description":"The date and time the resource is created.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"},"updated_at":{"description":"The date and time the resource is updated.","type":"string","example":"2024-01-10T20:16:35.343Z","format":"date-time"}}}}}},"title":"custom_relationship"}},"title":"single_custom_relationship"},"examples":{"updated-custom-relationship":{"summary":"Updated","value":{"data":{"type":"custom-relationship","id":"f3297ee8-da90-45e9-ae56-a2654aebbdfe","attributes":{"name":"Related Products","description":"A list of related products shown on the PDP","slug":"CRP_related_products","sort_order":5,"external_name":"Similar items to consider","external_description":"Check out these similar products that may also meet your needs or match your preferences.","bi_directional":false},"meta":{"owner":"store","timestamps":{"created_at":"2024-01-10T20:16:35.343Z","updated_at":"2024-01-10T20:16:35.343Z"}}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a hierarchy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a hierarchy"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/hierarchies/{hierarchyID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

```mdx-code-block
import CASummary from '/docs/partials/pxm/custom-attributes/custom-attribute-spec-summary.mdx';

Updates a hierarchy. You can do a partial update, where you specify only the field value to change.

<CASummary />
```

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier of the hierarchy. Must match the hierarchy ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"],"example":"hierarchy"},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The name of the hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description of the hierarchy.","type":"string"},"slug":{"description":"A unique slug for the hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized name for the hierarchy.","type":"string"},"description":{"description":"A localized description for the hierarchy.","type":"string"}}}}},"title":"req_attributes_hierarchy"}}}},"title":"update_hierarchy"},"examples":{"update-hierarchy":{"value":{"data":{"type":"hierarchy","id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","attributes":{"description":"Shoes Category Updated","admin_attributes":{"cost_of_goods":"42.0","charge_type":null},"shopper_attributes":{"cost_of_goods":null,"charge_type":"credit card"},"locales":{"fr-FR":{"name":"Chaussures mises à jour","description":"Catégorie de chaussures mise à jour"}},"name":"Shoes Updated","slug":"shoes"}}}}}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the updated hierarchy","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","meta","relationships","attributes"],"properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `hierarchy`.","type":"string","enum":["hierarchy"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"description":{"description":"A description for a hierarchy.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes_hierarchy"},"relationships":{"type":"object","properties":{"children":{"description":"The child nodes related to the hierarchy.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships_hierarchy"},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a hierarchy is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a hierarchy is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the hierarchy has child nodes.","type":"boolean"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"A unique identifier generated when a hierarchy is created.","type":"string"},"name":{"description":"The name of a hierarchy, such as `Major Appliances`.","type":"string"},"slug":{"description":"A unique slug for a hierarchy.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"hierarchy"}},"title":"single_hierarchy"},"examples":{"updated-hierarchy":{"value":{"data":{"type":"hierarchy","id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","attributes":{"description":"Shoes Category Updated","locales":{"fr-FR":{"name":"Chaussures mises à jour","description":"Catégorie de chaussures mise à jour"}},"admin_attributes":{"cost_of_goods":"42.0"},"shopper_attributes":{"charge_type":"credit card"},"name":"Shoes Updated","slug":"shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/children"}}},"meta":{"created_at":"2024-01-10T20:16:35.343Z","owner":"store","updated_at":"2024-01-10T20:30:50.867Z","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes Updated","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}}]}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a modifier(Products)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a modifier"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/variations/{variationID}/options/{optionID}/modifiers/{modifierID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the modifier is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"optionID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the option."},{"name":"modifierID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the modifier."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes","id"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `product-variation-modifier`.","type":"string","enum":["product-variation-modifier"]},"attributes":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"description":"You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n","type":"string","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"description":"Required for non-builder modifiers. The value of the modifier type.","type":"string"},"seek":{"description":"Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.","type":"string"},"set":{"description":"Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.","type":"string"},"reference_name":{"description":"The name of the modifier.","type":"string"}}},"id":{"type":"string","description":"The unique identifier of the modifier. Must match the modifier ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"}}}},"title":"update_modifier"},"examples":{"update-variation-modifier":{"value":{"data":{"type":"product-variation-modifier","id":"68ec4892-9e4c-4154-a9fd-f5a9fb1f6878","attributes":{"type":"sku_equals","value":"anotherSku"}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the updated modifier.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"A unique identifier for a modifier that is generated automatically when a modifier is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation-modifier`.","type":"string","enum":["product-variation-modifier"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"type":{"description":"You can specify different modifiers for different options in a variation. When you build child products using options in variations, the properties of a child products depends on the modifier set for the options that are applied to the child product. The table below describes the different types of modifiers.\n\n| Modifier | Data Type | Effect |\n| :--- | :--- | :--- |\n| `name_equals` | `string` | Overrides the name of the child product with the name specified by the modifier. |\n| `name_append` | `string` | Appends the string specified in the modifier to the name of the child product. |\n| `name_prepend` | `string` | Prepends the string specified in the modifier to the name of the child product. |\n| `description_equals` | `string` | Overrides the description of the child product. |\n| `description_append` | `string` | Appends the string specified in the modifier to the description of the child product. |\n| `description_prepend` | `string` | Prepends the string specified in the modifier to the product description of the child product. |\n| `commodity_type` | `string` | Sets the commodity type of the child product, such as `physical` or `digital`. |\n| `price` | `string` | Allows application of price modifiers (`price_increment`, `price_decrement`, and `price_equals`) to the child products. |\n| `price_increment` | `string` | Increases the price of the child product. |\n| `price_decrement` | `string` | Decreases the price of the child product. |\n| `price_equals` | `string` | Sets the price of a child product to the amount you specify. |\n| `slug_append` | `string` | Appends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_prepend` | `string` | Prepends the string specified in the modifier to the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `slug_builder` | `string`| Sets a part of the slug of the child product. Can only contain A-Z, a-z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. However, for the `slug-builder` modifier, you can use `{}` in the `seek` field, for example, `\"seek\": :{COLOR}\"`. |\n| `sku_equals` | `string` | Sets the SKU of the child product. |\n| `sku_append` | `string` | Appends the string specified in the modifier to the SKU of the child product. |\n| `sku_prepend` | `string` | Prepends the string specified in the modifier to the SKU of the child product. |\n| `sku_builder` | `string` | Sets a part of the SKU of the child product. |\n| `status` | `string` | Sets the status of the child product, such as `draft` or `live`. |\n","type":"string","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"description":"Required for non-builder modifiers. The value of the modifier type.","type":"string"},"seek":{"description":"Required for builder modifiers. The sub-string to find and replace enclosed in curly brackets for `slug_builder` and `sku_builder`.","type":"string"},"set":{"description":"Required for builder modifiers. The value to replace matches the `seek` string for `slug_builder` and `sku_builder`.","type":"string"},"reference_name":{"description":"The name of the modifier.","type":"string"}}},"meta":{"type":"object","description":"The owner of the resource, either `organization` or `store`.","properties":{"owner":{"type":"string","enum":["organization","store"]}}}}}},"title":"single_modifier"},"examples":{"updated-variation-modifier":{"value":{"data":{"type":"product-variation-modifier","id":"68ec4892-9e4c-4154-a9fd-f5a9fb1f6878","attributes":{"type":"sku_equals","value":"newSku"},"meta":{"owner":"store"}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a node's parent

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a node's parent"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}/relationships/parent"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Changes the parent of the specified node. The new parent node must be located within the same hierarchy as the specified node.

You cannot move a node to another hierarchy. If you want to put the specified node into another hierarchy, create the node in the target hierarchy and delete it from the current hierarchy.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier of the new parent node. Must not match the node ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]}}}},"title":"node_parent"},"examples":{"update-node-parent":{"value":{"data":{"type":"node","id":"60dc3982-ab34-47e8-9173-c920c63dc382"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a node

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a node"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/hierarchies/{hierarchyID}/nodes/{nodeID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

```mdx-code-block
import CASummary from '/docs/partials/pxm/custom-attributes/custom-attribute-spec-summary.mdx';

Updates the specified node in a hierarchy. You can do a partial update, where you specify only the field value to change.

<CASummary />  
```

### Sorting Nodes in a Hierarchy

You can sort the order of your nodes, regardless of where the nodes are in the hierarchy.
  
 The node with the highest value of sort_order is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`.
  
 - If you don’t provide `sort_order` when creating nodes, all child nodes in the response for Get a Node’s Children request are ordered by the `updated_at` time in descending order, with the most recently updated child node first.
 - If you set `sort_order` for only a few child nodes or not all, the child nodes with a `sort_order` value appear first and then other child nodes appear in the order of `updated_at` time.
  
 You can also specify a sort_order when creating a node relationship.

 - If you update a node (**Node A**) with a `sort_order` and then you create a relationship for **Node A** with another node (**Node B**), the `sort_order` you specified when updating **Node A** is overwritten.
 - If you have updated **Node A** and then you create a relationship with **Node B** but do not configure a `sort_order`, the `sort_order` you specified when you updated **Node A** is not overwritten.
  
 ### Curating Products in a Node

 You can curate the products in a node. Product curation allows you to promote specific products within each node of your hierarchies, enabling you to create unique product collections in your storefront. For example, you may find you have an abundance of cotton T-Shirts and you want to promote these products to the top of the product list. When a shopper navigates to T-shirts, the cotton T-Shirts are displayed first.

 You can do this by adding a `curated_products` attribute to the body of your request and adding an array of product IDs to the attribute. You should add the products IDs in the order you want them to be displayed in your node. The first product ID is displayed first in the product list.

 You can only curate 20 products or less. You cannot have more than 20 curated products.
  
 - The product IDs you provide must exist in the specified node.
 - If a curated product is removed from a node, the product is also removed from the curated_products list.
 - Once you have curated the products in a node, you can use the get node products endpoint to retrieve a list of curated products.
  
 You can then display your curated products in your catalogs using the following catalog endpoints.
  
 - [Get a node in your latest catalog release](/docs/api/pxm/catalog/get-node)
 - [Get a node in a catalog](/docs/api/pxm/catalog/get-by-context-node)
 - [Get all nodes in your latest catalog release](/docs/api/pxm/catalog/get-all-nodes)
 - [Get all nodes in a catalog](/docs/api/pxm/catalog/get-by-context-all-nodes)
 - [Get node children in your latest catalog release](/docs/api/pxm/catalog/get-child-nodes)
 - [Get node children in a catalog](/docs/api/pxm/catalog/get-by-context-child-nodes)

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"hierarchyID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the hierarchy."},{"name":"nodeID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the node."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier of the node. Must match the node ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description of the node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront. See [Curating Products in a Node](/docs/api/pxm/products/create-node#curating-products-in-a-node).","type":"array","items":{"description":"A list of product IDs for the products that you want to curate in a node.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized name for the node.","type":"string"},"description":{"description":"A localized description for the node.","type":"string"}}}}},"title":"attributes_nodes"},"meta":{"type":"object","additionalProperties":false,"properties":{"sort_order":{"description":"You can sort the order of your nodes, regardless of where the nodes are in the hierarchy. The `sort_order` for each node. This value determines the order of nodes in the response for the `Get a Node’s Children` request. The node with the highest value of sort_order is displayed first. For example, a node with a sort_order value of 3 appears before a node with a sort_order value of 2.\n \n- If you don’t provide `sort_order` when creating nodes, all child nodes in the response for `Get a Node’s Children` request are ordered by the `updated_at` time in descending order, with the most recently updated child node first.\n- If you set `sort_order` for only a few child nodes or not all, the child nodes with a `sort_order` value appear first and then other child nodes appear in the order of `updated_at` time.\n","type":"integer"}}}}}},"title":"update_node"},"examples":{"update-node":{"value":{"data":{"type":"node","id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","attributes":{"name":"Ballet Shoes","description":"Latest Ballet Shoes","slug":"ballet-shoes","admin_attributes":{"cost_of_goods":"42.0","charge_type":null},"shopper_attributes":{"cost_of_goods":null,"charge_type":"credit card"},"locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}}},"meta":{"sort_order":5}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the updated node","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"properties":{"id":{"description":"The unique identifier of a node.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"attributes":{"type":"object","properties":{"name":{"description":"The name of the node, such as `Ranges` or `Refrigerators`. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"description":{"description":"A description for a node.","type":"string"},"slug":{"description":"A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.","type":"string"},"curated_products":{"description":"You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.","type":"array","items":{"description":"A list of product IDs whose products you want to curate.","type":"string"}},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"},"description":{"description":"A localized hierarchy or node description.","type":"string"}}}}},"title":"attributes"},"relationships":{"type":"object","description":"Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.","properties":{"children":{"description":"The child nodes related to the resource.","type":"object","properties":{"data":{"description":"An array of child nodes.","type":"array","items":{}},"links":{"description":"Links allow you to move between requests.","type":"object","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}},"parent":{"description":"The parent node related to the resource","type":"object","properties":{"data":{"description":"The parent node","type":"object","required":["id","type"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `node`.","type":"string","enum":["node"]},"id":{"description":"The unique identifier of a node.","type":"string"}}}}},"products":{"type":"object","description":"The products related to the resource.","properties":{"data":{"description":"An array of products.","type":"array","items":{}},"links":{"type":"object","description":"Links allow you to move between requests.","properties":{"related":{"description":"A link to a related resource.","type":"string"}}}}}},"title":"relationships"},"meta":{"type":"object","properties":{"sort_order":{"description":"The sort order value. The node with the highest value of `sort_order` is displayed first. For example, a node with a `sort_order` value of `3` appears before a node with a `sort_order` value of `2`. See [Sorting Nodes in a hierarchy](/docs/api/pxm/products/create-node#sorting-nodes-in-a-hierarchy).","type":"integer"},"created_at":{"description":"The date and time a node is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a node was updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"parent_name":{"description":"The name of the parent of the node if one exists.","type":"string"},"owner":{"description":"The node owner, either `organization` or `store`.","type":"string","enum":["store","organization"]},"has_children":{"description":"Whether the node has child nodes.","type":"boolean"},"hierarchy_id":{"description":"The unique identifier of hierarchy","type":"string"},"breadcrumbs":{"type":"array","description":"Breadcrumbs","items":{"type":"object","properties":{"id":{"description":"The unique identifier of a hierarchy/node.","type":"string"},"name":{"description":"The name of the hierarchy/node.","type":"string"},"slug":{"description":"A slug for the hierarchy/node.","type":"string"},"locales":{"description":"Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.","type":"object","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","additionalProperties":false,"properties":{"name":{"description":"A localized hierarchy or node name.","type":"string"}}}}}}}}}},"title":"node"}},"title":"single_node"},"examples":{"updated-node":{"value":{"data":{"type":"node","id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","attributes":{"description":"Latest Ballet Shoes","locales":{"fr-FR":{"name":"Chaussons de ballet","description":"Dernières chaussures de ballet"}},"admin_attributes":{"cost_of_goods":"42.0"},"shopper_attributes":{"charge_type":"credit card"},"name":"Ballet Shoes","slug":"ballet-shoes"},"relationships":{"children":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"}},"products":{"data":[],"links":{"related":"/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"}}},"meta":{"created_at":"2024-01-11T19:19:50.087Z","owner":"store","sort_order":5,"updated_at":"2024-01-11T19:56:53.695Z","hierarchy_id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","breadcrumbs":[{"id":"6183d10c-94b5-4caa-9f12-2f14cb738d41","name":"Shoes","slug":"shoes","locales":{"fr-FR":{"name":"hierarchy 1 in French"}}},{"id":"9ea0de15-3347-43dd-8faa-cd32f44a04c7","name":"Ballet Shoes","slug":"ballet-shoes","locales":{"fr-FR":{"name":"Node 1 in French"}}}]}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Replace a product file relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Replace a product file relationship"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/products/{productID}/relationships/files"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Replace a product file relationship

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a file generated when a file is created.","type":"string"},"type":{"description":"This represents the type of resource being returned. Always `file`.","type":"string","enum":["file"]},"meta":{"type":"object","properties":{"tags":{"description":"The files associated with a product.","type":"array","items":{"type":"string"}}},"additionalProperties":false}}}}},"title":"product_files_request"},"examples":{"replace-product-file-relationship":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"file"},{"id":"50f56ce9-9381-43f6-8a52-5369a8b42e52","type":"file"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Replace Main Image Relationships

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Replace Main Image Relationships"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/products/{productID}/relationships/main_image"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Replace Main Image Relationships

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the new image file.","example":"00000000-0000-0000-0000-000000000000"},"type":{"type":"string","enum":["file"]}}}},"title":"replace_main_image_request"},"examples":{"replace-main-image-relationship":{"value":{"data":{"type":"file","id":"3ab3deca-1f11-47b7-a409-24ea3234d72c"}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Replace a product variation relationship

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Replace a product variation relationship"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/products/{productID}/relationships/variations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Replace a product variation relationship

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the product variation."},"type":{"type":"string","enum":["product-variation"],"description":"This represents the type of resource being returned. Always `product-variation`."}}}}},"title":"product_variations_request"},"examples":{"replace-product-variation-relationship":{"value":{"data":[{"id":"43903bfa-5352-4a3d-9496-c9ab1229a175","type":"product-variation"}]}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"bad-request":{"value":{"errors":[{"title":"Bad Request","detail":"Could not parse the supplied filter","status":"400"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a product or bundle

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a product or bundle"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/products/{productID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the product or bundle is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"productID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{productID}}"},"required":true,"description":"A unique identifier for the product."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes","id"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"],"example":"product"},"id":{"type":"string","description":"The unique identifier of the product. Must match the product ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"},"attributes":{"type":"object","additionalProperties":false,"properties":{"external_ref":{"type":"string","description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters."},"name":{"type":"string","description":"The product name to display to customers."},"description":{"description":"A description for the product.","type":"string"},"slug":{"type":"string","description":"The unique slug of the product. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed."},"sku":{"type":"string","description":"The unique stock keeping unit of the product."},"status":{"type":"string","enum":["live","draft"],"description":"The status for the product, either `draft` or `live`. Default is `draft`.  For a product to appear in a catalog it must be in a `live` status."},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"type":"string","description":"The universal product code or european article number of the product."},"mpn":{"type":"string","description":"The manufacturer part number of the product."},"tags":{"type":"array","description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas. See [Product Tags](/docs/api/pxm/products/product-tags).","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}},"title":"product_attributes"}}}},"title":"update_product_request"},"examples":{"update-product":{"summary":"Update a base product","value":{"data":{"type":"product","id":"60afe403-a191-455e-b771-c510c928a308","attributes":{"name":"UPDATED BestEver Range, Model 1a1a"}}}},"update-product-build-rules":{"summary":"Update a base product and build rules","value":{"data":{"type":"product","id":"9214719b-17fe-4ea7-896c-d61e60fc0d05","attributes":{"build_rules":{"default":"include","exclude":[["cbde9096-e0e1-43d8-a1aa-cb66cf1d299f","0b261f7d-753d-4af6-b9f4-62b436cca37d","994c2029-519c-43d9-9c54-14f3af4e3efd"]]}}}}},"update-product-custom-inputs":{"summary":"Update using custom_inputs","description":"You can allow your shoppers to add custom text to a product when checking out their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized. You can do this using the custom_inputs attribute when creating your products.","value":{"data":{"type":"product","id":"9214719b-17fe-4ea7-896c-d61e60fc0d05","attributes":{"custom_inputs":{"front":{"name":"T-Shirt Front","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false},"back":{"name":"T-Shirt Back","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false}}}}}},"update-product-bundle":{"summary":"Update a bundle","value":{"data":{"id":"8a0072c0-cedf-4e53-bdc4-a14a5d6389d5","type":"product","attributes":{"name":"Favourite games bundle","description":"Favourite DOOM games in one bundle - Select one from four choices","sku":"fav23455","mpn":"1234-5678-ABCD00","upc_ean":"123456","commodity_type":"digital","status":"live","components":{"List 1":{"name":"PS5","sort_order":1,"options":[{"id":"c7cf43f3-24c6-4523-8a24-3663b49b81aa","type":"product","quantity":1,"default":true}]},"List 2":{"name":"Controller","sort_order":2,"options":[{"id":"e59ca559-37c7-4dc9-8a91-df94cd5700d3","type":"product","quantity":1,"default":true}]},"List 3":{"name":"PS+","sort_order":3,"options":[{"id":"8ae2a7ea-f767-4af0-8486-ae203947ecc4","type":"product","quantity":1,"default":true}]},"List 4":{"min":1,"max":1,"sort_order":4,"options":[{"id":"549a291f-669c-47d0-bc04-60a3f18fc55c","type":"product","quantity":1,"default":true,"sort_order":2},{"id":"071e461c-22a2-42e0-9604-c345bbc9b85c","type":"product","quantity":1,"default":false,"sort_order":1},{"id":"633b8172-8aa9-4dbd-aa07-0dcefca3de74","type":"product","quantity":1,"default":false},{"id":"549a291f-669c-47d0-bc04-60a3f18fc55c","type":"product","quantity":1,"default":false,"sort_order":3}]}}}}}},"update-product-bundle-quantity-config":{"summary":"Update Bundle with Quantity Configuration","description":"Update a bundle where each selected option can have a configurable quantity. In this example, syrup is optional (0-2 types) with up to 3 pumps per syrup, and exactly one coffee type must be selected.","value":{"data":{"id":"143e9ded-b549-4631-831c-d27f5fb2fe2e","type":"product","attributes":{"name":"Coffee Bundle","description":"A customizable coffee bundle with optional syrups and coffee options","sku":"COFFEE-BUNDLE-001","commodity_type":"physical","status":"live","components":{"syrup":{"name":"Syrup Selection","min":0,"max":2,"options":[{"id":"vanilla-id","type":"product","quantity":1,"min":1,"max":3,"default":true},{"id":"salted-caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"hazelnut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"toffee-nut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"pumpkin-spice-id","type":"product","quantity":1,"min":1,"max":3}]},"coffee":{"name":"Coffee Selection","min":1,"max":1,"options":[{"id":"cappuccino-id","type":"product","quantity":1,"default":true},{"id":"espresso-id","type":"product","quantity":1},{"id":"latte-id","type":"product","quantity":1}]}}}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Updates a product with the following attributes.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"},"included":{"type":"object","description":"Included is an array of resources that are included in the response.","properties":{"main_images":{"description":"The main images associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}},"component_products":{"description":"Returns a list of component products in a product bundle. If a bundle has no component products (in other words, is not a product bundle), an empty array is returned.","type":"array","items":{"type":"object","properties":{"id":{"description":"A unique product ID that is generated when you create the product.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product`.","type":"string","enum":["product"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name for the product.","type":"string"},"description":{"description":"A description for the product.","type":"string"},"slug":{"description":"A label for the product that is used in the URL paths. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed. By default, the product name is used as the slug.","type":"string"},"sku":{"description":"The unique stock keeping unit of the product.","type":"string"},"status":{"description":"The status for the product, either `draft` or `live`.","type":"string","enum":["live","draft"]},"commodity_type":{"description":"The commodity type, either `physical` or `digital`.","type":"string","enum":["physical","digital"]},"upc_ean":{"description":"The universal product code or european article number of the product.","type":"string"},"mpn":{"description":"The manufacturer part number of the product.","type":"string"},"external_ref":{"description":"The unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.","type":"string"},"locales":{"type":"object","description":"Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.","additionalProperties":{"description":"A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.","type":"object","required":["name"],"properties":{"name":{"type":"string","description":"A localized name for the product."},"description":{"type":"string","description":"A localized description for the product."}}},"title":"product_locales"},"tags":{"description":"You can use product tags to store or assign a key word against a product. The product tag can then be used to describe or label that product. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. A product can have up to 20 tags. A product tag can be up to 255 characters. Product tags must not contain any spaces or commas.","type":"array","items":{"type":"string"}},"shopper_attributes":{"type":"object","description":"`shopper_attributes` are displayed in catalogs. This means `shopper_attributes` can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to `admin_attributes`. \n\n`shopper_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"shopper_attributes"},"admin_attributes":{"type":"object","description":"`admin_attributes` are not displayed in catalogs. This means `admin_attributes` can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to `shopper_attributes`. \n\n`admin_attributes` are structured as key-value pairs. Both the keys and values are `strings`. You can have up to 100 keys.\n","example":{"cost_of_goods":"42.0","charge_type":"credit card"},"additionalProperties":{"nullable":true,"type":"string"},"title":"admin_attributes"},"extensions":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"oneOf":[{"type":"string","nullable":true},{"type":"number"},{"type":"boolean"}]}}},"custom_inputs":{"type":"object","description":"You use the `custom_inputs` attribute to allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. See [Personalizing Products](/docs/api/pxm/products/create-product#personalizing-products).","additionalProperties":{"description":"A name for the custom text field. You can rename this to something more representative of the input that shoppers are adding, for example, `message` or `front`.","type":"object","properties":{"name":{"type":"string","description":"A name for the custom text field."},"validation_rules":{"type":"array","description":"The validation rules for the custom text.","items":{"type":"object","properties":{"type":{"type":"string","description":"The type of validation rule. For example, `string`."},"options":{"type":"object","description":"The options for the validation rule.","properties":{"max_length":{"type":"integer","description":"The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters."}}}}}},"required":{"type":"boolean","description":"`true` or `false` depending on whether the custom text is required."}}},"title":"product_custom_inputs"},"build_rules":{"type":"object","description":"You can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Using Build Rules](/docs/api/pxm/products/build-child-products#using-build-rules).","properties":{"default":{"description":"Specifies the default behaviour, either `include` or `exclude`.","type":"string","enum":["include","exclude"]},"include":{"description":"An array of option IDs to include when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}},"exclude":{"description":"An array of option IDs to exclude when child products are built. Each combination consists of a nested array of option IDs from one or more variations. Combinations of option IDs in the nested arrays must come from different variations.","type":"array","items":{"type":"array","items":{"type":"string"}}}},"title":"product_build_rules"},"components":{"type":"object","description":"With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product, consisting of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. See [Bundles](/docs/api/pxm/products/products#bundles).","additionalProperties":{"description":"The name of the component, such as `games`. The `bundle_configuration` uses the component name to reference a component. A component name should be relatively short and must not contain any special characters.","type":"object","properties":{"name":{"type":"string","description":"The component name. The component name is the name that is displayed in your storefront."},"options":{"type":"array","description":"The product options included in a component. This can be the ID of another bundle.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique ID of the product you want to add to a component."},"type":{"type":"string","description":"This represents the type of object being returned. Always `product`."},"quantity":{"type":"integer","minimum":1,"description":"The number of this product option that a shopper must purchase."},"min":{"type":"integer","minimum":1,"description":"The minimum quantity of this product option that a shopper can select. Must be 1 or greater. If specified, max must also be specified."},"max":{"type":"integer","minimum":1,"description":"The maximum quantity of this product option that a shopper can select. Must be 1 or greater and greater than or equal to min. If specified, min must also be specified."},"sort_order":{"type":"integer","description":"The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want."},"default":{"description":"Whether the product option is a default option in a bundle. Shoppers can select a bundle that specifies a default list of product options. See [Dynamic Bundles](/docs/api/pxm/products/products#dynamic-bundles).","type":"boolean"},"product_should_be_substituted_with_child":{"description":"Whether the product option should be substituted with a child product.","type":"boolean"},"excluded_children":{"description":"The IDs of child products that are excluded from the bundle option.","type":"array","items":{"type":"string"}}}}},"min":{"type":"integer","description":"The minimum number of product options a shopper can select from this component."},"max":{"type":"integer","description":"The maximum number of product options a shopper can select from this component."},"sort_order":{"type":"integer","description":"The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want."}}},"title":"product_bundle_components"}}},"meta":{"type":"object","properties":{"created_at":{"description":"The date and time a product is created.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"description":"The date and time a product is updated.","type":"string","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"owner":{"description":"The resource owner, either `organization` or `store`.","type":"string","enum":["organization","store"]},"variations":{"description":"A product's variations and the options defined for each variation. If you have specified `build_rules`, only the child products included in the `build_rules` are specified.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"type":"integer","description":"The sort order of the variation."},"options":{"type":"array","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}}},"custom_relationships":{"description":"Custom relationship slugs that are attached to the product.","type":"array"},"child_variations":{"description":"A child product's variations and the option defined for each variation. This details the variation and options specific to a child product.","type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string","description":"A unique ID generated when a variation is created."},"name":{"type":"string","description":"The name of a variation."},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"options":{"type":"array","nullable":true,"description":"This will be unset for child product variations.","items":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}},"option":{"type":"object","description":"The options available for this variation.","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"The name of an option."},"description":{"type":"string","description":"A description of an option."},"sort_order":{"type":"integer","description":"The sort order of the option."}}}}}},"product_types":{"description":"One of the following product types: \n\n- `standard` - A `standard` product is a standalone product.\n- `parent` - A `parent` product is a product that has child products that have been built using the `Build Child Products` endpoint. \n- `child` - When you configure product variations and variation options for `parent` products, the `child` products derived from the `parent` products are automatically created in Commerce.\n- `bundle` - A `bundle` is a purchasable product, comprising one or more standalone products (in other words, components) to be sold together.\n","type":"array","items":{"type":"string","enum":["parent","child","bundle","standard"]}},"variation_matrix":{"description":"The child products defined for a product. The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. See [Sorting the Order of Variations and Options](/docs/api/pxm/products/variations#sorting-the-order-of-variations-and-options) If no variations are defined for a product, the `variation_matrix` is empty.","type":"object","additionalProperties":true}}},"relationships":{"description":"Relationships are established between different product entities. For example, a `bundle` product and a `child` product are related to a `parent` product, as both are associated with it.","type":"object","additionalProperties":{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}},{"type":"object","nullable":true,"properties":{"id":{"description":"A unique identifier for a resource.","type":"string"},"type":{"description":"This represents the type of resource object being returned.","type":"string"}}}]},"links":{"description":"Links are used to allow you to move between requests. Single entities use a `self` parameter with a link to that specific resource. Sometimes, there are not enough entities for a project to fill multiple pages. In this situation, we return some defaults.\n\n | Property | Description |\n | :--- | :--- |\n | `current` | Always the current page. |\n | `first` | Always the first page. |\n | `last` | `null` if there is only one page. |\n | `prev` | `null` if the user is on the first page. |\n | `next` | `null` if there is only one page. |\n","type":"object","additionalProperties":{"type":"string"}}}}}},"title":"product_response"}},"files":{"description":"The files associated with a product.","type":"array","items":{"type":"object","title":"ElasticPathFile","properties":{"id":{"type":"string","description":"The unique identifier for this file.","format":"uuid"},"type":{"description":"The type represents the object being returned.","type":"string","example":"file"},"file_name":{"description":"The name of the file.","type":"string","example":"file_name.jpg"},"mime_type":{"description":"The mime type of the file.","type":"string","example":"image/jpeg"},"file_size":{"description":"The size of the file. Required when uploading files.","type":"integer","example":36000},"public":{"description":"DEPRECATED Whether the file public or not. Required when uploading files.","type":"boolean","example":true},"meta":{"properties":{"timestamps":{"type":"object","description":"The date and time the file was created.","properties":{"created_at":{"description":"The date and time the file was created.","type":"string","example":"2023-10-11T13:02:25.293Z"}}},"dimensions":{"description":"The file dimensions.","type":"object","properties":{"width":{"description":"The width of the file.","type":"integer","example":1800},"height":{"description":"The height of the file.","type":"integer","example":1000}}}}},"links":{"description":"Links are used to allow you to move between requests.","type":"object","properties":{"self":{"description":"Single entities use a self parameter with a link to that specific resource.","type":"string","example":"https://useast.api.elasticpath.com/v2/files/ddc28c74-a7df-46be-b262-8fa69a6e7d52"}}},"link":{"type":"object","description":"The publicly available URL for this file.","properties":{"href":{"description":"The publicly available URL for this file.","type":"string","example":"https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/f8cf26b3-6d38-4275-937a-624a83994702.png"},"meta":{"type":"object","properties":{"results":{"description":"Contains the results for the entire collection.","type":"object","properties":{"total":{"description":"Total number of results for the entire collection.","type":"integer","example":2}}}}}}}}}}},"title":"included_response"}},"title":"single_product_response"},"examples":{"updated-product":{"summary":"Update a base product","value":{"data":{"type":"product","id":"60afe403-a191-455e-b771-c510c928a308","attributes":{"commodity_type":"physical","description":"The 30 inch version of this popular electric range.","mpn":"BE-R-1111-aaaa-1a1a-30","name":"UPDATED BestEver Range 30 inch, Model 1a1a-30","sku":"BE-Range-1a1a-30","slug":"bestever-range-1a1a-30","status":"draft","upc_ean":"111130303030","locales":{"fr-FR":{"name":"MISE À JOUR de la gamme BestEver 30 pouces, modèle 1a1a-30","description":"La version 30 pouces de cette cuisinière électrique populaire"}},"tags":["tag1","tag2"]},"relationships":{"files":{"data":[],"links":{"self":"/products/60afe403-a191-455e-b771-c510c928a308/relationships/files"}},"templates":{"data":[],"links":{"self":"/products/60afe403-a191-455e-b771-c510c928a308/relationships/templates"}}},"meta":{"created_at":"2023-09-28T10:43:41.72Z","owner":"organization","product_types":["standard"],"updated_at":"2023-09-28T10:43:41.72Z"}}}},"build-rules":{"summary":"Update a base product, configure build rules","value":{"data":{"type":"product","id":"9214719b-17fe-4ea7-896c-d61e60fc0d05","attributes":{"build_rules":{"default":"include","exclude":[["cbde9096-e0e1-43d8-a1aa-cb66cf1d299f","0b261f7d-753d-4af6-b9f4-62b436cca37d","994c2029-519c-43d9-9c54-14f3af4e3efd"]]},"commodity_type":"physical","description":"T-shirt.","locales":{"fr-FR":{"name":"Shirt","description":"T-Shirt."}},"mpn":"1234-5678-SSSS","name":"Shirt","sku":"978055216732567","slug":"978055216732567","status":"live","upc_ean":"135623456"},"relationships":{"children":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/children"}},"component_products":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/variations"}}},"meta":{"created_at":"2022-08-18T12:14:52.782Z","owner":"store","product_types":["standard"],"updated_at":"2022-08-18T12:40:13.484Z","variation_matrix":{},"variations":[{"id":"6c4b5caa-3819-4366-a14e-c5b85009544b","name":"Shirt Size","options":[{"id":"cbde9096-e0e1-43d8-a1aa-cb66cf1d299f","name":"Small","description":"Size Small"},{"id":"da9d88d0-8ea6-434c-a0dd-059caf595687","name":"Medium","description":"Size Medium"},{"id":"07493fea-74b0-40a2-972a-cd7e1d6561bd","name":"Large","description":"Size Large"}]},{"id":"b1ae545e-3375-455f-b5ea-09669b60996f","name":"Shirt Material","options":[{"id":"994c2029-519c-43d9-9c54-14f3af4e3efd","name":"Cotton","description":"Material Cotton"},{"id":"7951f3d9-f628-49f8-8a43-7749d28153d6","name":"Denim","description":"Material Denim"},{"id":"58115bff-589a-4287-98d8-373112102617","name":"Wool","description":"Material Wool"}]},{"id":"f192e114-9f8a-4284-99d0-4d9ccd8a0275","name":"Shirt Color","options":[{"id":"0b261f7d-753d-4af6-b9f4-62b436cca37d","name":"Red","description":"Color Red"},{"id":"55d6d785-cc52-453a-bff6-2cf9add8a580","name":"Green","description":"Color Green"},{"id":"a43d8b6f-b411-49aa-adaa-36a1a025051e","name":"Blue","description":"Color Blue"}]}]}}}},"update-product-custom-inputs":{"summary":"Update using custom_inputs","value":{"data":{"type":"product","id":"9214719b-17fe-4ea7-896c-d61e60fc0d05","attributes":{"commodity_type":"physical","custom_inputs":{"back":{"name":"T-Shirt Back","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false},"front":{"name":"T-Shirt Front","validation_rules":[{"type":"string","options":{"max_length":50}}],"required":false}},"description":"T-shirt.","locales":{"fr-FR":{"name":"T-Shirt","description":"T-Shirt."}},"mpn":"1234-5678-SSSS","name":"Shirt","sku":"978055216732567","slug":"978055216732567","status":"live"},"relationships":{"children":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/children"}},"component_products":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/9214719b-17fe-4ea7-896c-d61e60fc0d05/relationships/variations"}}},"meta":{"created_at":"2022-08-18T12:14:52.782Z","updated_at":"2022-08-19T12:28:26.343Z","variation_matrix":{},"variations":[{"id":"6c4b5caa-3819-4366-a14e-c5b85009544b","name":"Shirt Size","options":[{"id":"cbde9096-e0e1-43d8-a1aa-cb66cf1d299f","name":"Small","description":"Size Small"},{"id":"da9d88d0-8ea6-434c-a0dd-059caf595687","name":"Medium","description":"Size Medium"},{"id":"07493fea-74b0-40a2-972a-cd7e1d6561bd","name":"Large","description":"Size Large"}]},{"id":"b1ae545e-3375-455f-b5ea-09669b60996f","name":"Shirt Material","options":[{"id":"994c2029-519c-43d9-9c54-14f3af4e3efd","name":"Cotton","description":"Material Cotton"},{"id":"7951f3d9-f628-49f8-8a43-7749d28153d6","name":"Denim","description":"Material Denim"},{"id":"58115bff-589a-4287-98d8-373112102617","name":"Wool","description":"Material Wool"}]},{"id":"f192e114-9f8a-4284-99d0-4d9ccd8a0275","name":"Shirt Color","options":[{"id":"0b261f7d-753d-4af6-b9f4-62b436cca37d","name":"Red","description":"Color Red"},{"id":"55d6d785-cc52-453a-bff6-2cf9add8a580","name":"Green","description":"Color Green"},{"id":"a43d8b6f-b411-49aa-adaa-36a1a025051e","name":"Blue","description":"Color Blue"}]}]}}}},"update-product-bundle":{"summary":"Update a bundle","value":{"data":{"type":"product","id":"8a0072c0-cedf-4e53-bdc4-a14a5d6389d5","attributes":{"commodity_type":"digital","components":{"List 1":{"name":"PS5","options":[{"id":"c7cf43f3-24c6-4523-8a24-3663b49b81aa","type":"product","quantity":1,"default":true}],"sort_order":1},"List 2":{"name":"Controller","options":[{"id":"e59ca559-37c7-4dc9-8a91-df94cd5700d3","type":"product","quantity":1,"default":true}],"sort_order":2},"List 3":{"name":"PS+","options":[{"id":"8ae2a7ea-f767-4af0-8486-ae203947ecc4","type":"product","quantity":1,"default":true}],"sort_order":3},"List 4":{"options":[{"id":"549a291f-669c-47d0-bc04-60a3f18fc55c","type":"product","quantity":1,"default":true},{"id":"071e461c-22a2-42e0-9604-c345bbc9b85c","type":"product","quantity":1,"default":false},{"id":"633b8172-8aa9-4dbd-aa07-0dcefca3de74","type":"product","quantity":1,"default":false},{"id":"549a291f-669c-47d0-bc04-60a3f18fc55c","type":"product","quantity":1,"default":false}],"min":1,"max":1,"sort_order":4},"headsets":{"name":"Headsets","options":[{"id":"8ae2a7ea-f767-4af0-8486-ae203947ecc4","type":"product","quantity":5,"default":true}]}},"description":"Favourite DOOM games in one bundle - Select one from four choices","mpn":"1234-5678-ABCD00","name":"Favourite games bundle","sku":"fav23455","slug":"PGH69345-B","status":"live","upc_ean":"123456"},"relationships":{"children":{"data":[],"links":{"self":"/products/8a0072c0-cedf-4e53-bdc4-a14a5d6389d5/children"}},"component_products":{"data":[],"links":{"self":"/products/8a0072c0-cedf-4e53-bdc4-a14a5d6389d5/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/8a0072c0-cedf-4e53-bdc4-a14a5d6389d5/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/8a0072c0-cedf-4e53-bdc4-a14a5d6389d5/relationships/templates"}},"variations":{"data":[],"links":{"self":"/products/8a0072c0-cedf-4e53-bdc4-a14a5d6389d5/relationships/variations"}}},"meta":{"created_at":"2022-02-03T19:38:00.602Z","owner":"store","updated_at":"2022-02-03T19:43:21.487Z","variation_matrix":{}}}}},"update-product-bundle-quantity-config":{"summary":"Update Bundle with Quantity Configuration","description":"A bundle where each selected option can have a configurable quantity. In this example, syrup is optional (0-2 types) with up to 3 pumps per syrup, and exactly one coffee type must be selected.","value":{"data":{"type":"product","id":"143e9ded-b549-4631-831c-d27f5fb2fe2e","attributes":{"name":"Coffee Bundle","description":"A customizable coffee bundle with optional syrups and coffee options","sku":"COFFEE-BUNDLE-001","commodity_type":"physical","status":"live","components":{"syrup":{"name":"Syrup Selection","min":0,"max":2,"options":[{"id":"vanilla-id","type":"product","quantity":1,"min":1,"max":3,"default":true},{"id":"salted-caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"hazelnut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"caramel-id","type":"product","quantity":1,"min":1,"max":3},{"id":"toffee-nut-id","type":"product","quantity":1,"min":1,"max":3},{"id":"pumpkin-spice-id","type":"product","quantity":1,"min":1,"max":3}]},"coffee":{"name":"Coffee Selection","min":1,"max":1,"options":[{"id":"cappuccino-id","type":"product","quantity":1,"default":true},{"id":"espresso-id","type":"product","quantity":1},{"id":"latte-id","type":"product","quantity":1}]}}},"relationships":{"children":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/children"}},"component_products":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/component_products"}},"files":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/files"}},"main_image":{"data":null},"templates":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/templates"}},"variations":{"data":[],"links":{"self":"/products/143e9ded-b549-4631-831c-d27f5fb2fe2e/relationships/variations"}}},"meta":{"created_at":"2024-04-14T10:34:00.000Z","owner":"organization","product_types":["bundle"],"updated_at":"2024-04-14T10:34:00.000Z","variation_matrix":{}}},"included":{"main_images":[],"files":[]}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a variation option

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a variation option"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/variations/{variationID}/options/{optionID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a variation option

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."},{"name":"optionID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000"},"required":true,"description":"A unique identifier for the option."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes","id"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `product-variation-option`.","type":"string","enum":["product-variation-option"]},"attributes":{"type":"object","additionalProperties":false,"required":["name","description"],"properties":{"name":{"description":"A human recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string"},"description":{"description":"The description of the option.","type":"string"},"sort_order":{"description":"By default, variations and variation options are sorted alphabetically. You can use the `sort_order` attribute to sort the order of your variation and variation options in the `variation_matrix`. The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want.  \n\nThe variation option with the highest value of `sort_order` is displayed first. For example, a variation option with a `sort_order` value of `3` appears before a variation option with a `sort_order` value of `2`. \n\nYou can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, and so on, zero or negative numbers. \n\nYou can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.\n\nYou must rebuild your products for the sort order changes to take effect.\n","type":"integer"}}},"id":{"type":"string","description":"The unique identifier of the option. Must match the option ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"}}}},"title":"update_option"},"examples":{"update-variation-option":{"value":{"data":{"type":"product-variation-option","id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","attributes":{"description":"Our most popular color","name":"Blue","sort_order":0}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successfully returns the updated variation option","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"The unique identifier generated when an option is created.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation-option`.","type":"string","enum":["product-variation-option"]},"attributes":{"type":"object","description":"A variation option represents an option for selection for a single product-variation. For example, if your variation is `color`, you might have three possible options; red, green, and blue.","additionalProperties":false,"properties":{"name":{"description":"A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.","type":"string"},"description":{"description":"A human-recognizable description for the option.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"}}},"meta":{"type":"object","properties":{"owner":{"description":"The owner of a resource, either `organization` or `store`.","type":"string","enum":["organization","store"]},"created_at":{"type":"string","description":"The date and time an option is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time an option is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"modifiers":{"type":"array","description":"The modifiers associated with this option.","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier generated when a modifier is created."},"type":{"type":"string","description":"The type of modifier.","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"type":"string","nullable":true,"description":"Required for non-builder modifiers. The value of the modifier type."},"seek":{"type":"string","nullable":true,"description":"Required for builder modifiers. The sub-string to find and replace."},"set":{"type":"string","nullable":true,"description":"Required for builder modifiers. The value to replace matches of the seek string."},"owner":{"type":"string","nullable":true,"description":"The owner of the modifier, either `organization` or `store`.","enum":["organization","store"]}}}}}}}}},"title":"single_option"},"examples":{"updated-variation-option":{"value":{"data":{"type":"product-variation-option","id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","attributes":{"description":"Our most popular color","name":"Blue","sort_order":0},"meta":{"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a variation

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a variation"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/pcm/variations/{variationID}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the variation is not updated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"variationID","in":"path","schema":{"type":"string","example":"00000000-0000-0000-0000-000000000000","x-postman-example":"{{variationID}}"},"required":true,"description":"A unique identifier for the variation."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes","id"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `product-variation`.","type":"string","enum":["product-variation"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The variation name.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. \n \n The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. \n \n You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.\n \n You must rebuild your products for the sort order changes to take effect.\n","type":"integer"}}},"id":{"type":"string","description":"The unique identifier of the variation. Must match the variation ID specified in the request path.","example":"00000000-0000-0000-0000-000000000000"}}}},"title":"update_variation"},"examples":{"update-variation":{"value":{"data":{"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"product-variation","attributes":{"name":"Paint Color","sort_order":0}}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Returns an updated variation with the following attributes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"properties":{"id":{"description":"A unique identifier for a variation.","type":"string"},"type":{"description":"This represents the type of resource object being returned. Always `product-variation`.","type":"string","enum":["product-variation"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"The name for a variation.","type":"string"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"}}},"meta":{"type":"object","properties":{"options":{"description":"A variation option represents an option for selection for a single product-variation. For example, if your variation is `color`, you might have three possible options; red, green, and blue.","type":"array","items":{"type":"object","description":"The options available for this variation","properties":{"id":{"type":"string","description":"A unique ID that is generated an option is created."},"name":{"type":"string","description":"A human-recognizable identifier for the option, also used in the SLUG for child products. Option names can only contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed."},"description":{"type":"string","description":"A description for an option."},"created_at":{"type":"string","description":"The date and time an option is created.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"updated_at":{"type":"string","description":"The date and time an option is updated.","example":"2020-09-22T09:00:00.000Z","format":"date-time"},"sort_order":{"description":"The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variation options in the order that you want. The variation with the highest value of `sort_order` is displayed first. For example, a variation with a `sort_order` value of 3 appears before a variation with a `sort_order` value of 2. You can specify any numbers that you want. You can use 1, 2, 3, or 100, 90, 80, including, zero or negative numbers. You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.","type":"integer"},"modifiers":{"type":"array","description":"The modifiers associated with this option.","items":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier generated when a modifier is created."},"type":{"type":"string","description":"The type of modifier.","enum":["commodity_type","status","price","name_append","name_prepend","name_equals","sku_append","sku_prepend","sku_equals","sku_builder","slug_append","slug_prepend","slug_equals","slug_builder","description_append","description_prepend","description_equals","custom_inputs_equals","build_rules_equals","locales_equals","upc_ean_equals","mpn_equals","external_ref_equals"]},"value":{"type":"string","nullable":true,"description":"Required for non-builder modifiers. The value of the modifier type."},"seek":{"type":"string","nullable":true,"description":"Required for builder modifiers. The sub-string to find and replace."},"set":{"type":"string","nullable":true,"description":"Required for builder modifiers. The value to replace matches of the seek string."},"owner":{"type":"string","nullable":true,"description":"The owner of the modifier, either `organization` or `store`.","enum":["organization","store"]}}}}}}},"owner":{"description":"The owner of the resource, either `organization` or `store`.","type":"string","enum":["organization","store"]},"created_at":{"type":"string","description":"The date and time a variation is created."},"updated_at":{"type":"string","description":"The date and time a variation is updated."}}}}}},"title":"single_variation"},"examples":{"update-variation":{"value":{"data":{"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"product-variation","attributes":{"name":"Paint Color","sort_order":1},"meta":{"options":[{"id":"3de2c96c-2a99-4ded-bcf8-eeba32c0c5be","name":"Red","description":"Red color","sort_order":2,"created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"},{"id":"31f2d09b-8a10-447a-b3ad-3358d07f818a","name":"Blue","description":"Blue color","sort_order":1,"created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}],"owner":"store","created_at":"2024-01-25T11:25:38.001Z","updated_at":"2024-01-25T11:25:38.001Z"}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Forbidden","status":"403","detail":"entity owned by organization"}]}}}}}},"404":{"description":"Bad Request. Not Found.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Not Found","status":"404"}]}}}}}},"409":{"description":"Write conflict detected","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Conflict","status":"409","detail":"write conflict detected"}]}}}}}},"422":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"failed-validation":{"value":{"errors":[{"title":"Failed Validation","status":"422","detail":"<XYZ> can not be empty"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"request_id":{"type":"string","description":"Internal request ID.","example":"00000000-0000-0000-0000-000000000000"},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}}}}},"title":"error"},"examples":{"internal-server-error":{"value":{"errors":[{"status":"500","title":"Internal Server Error","detail":"There was an internal server error, you can report with your request id.","request_id":"635da56d-75a1-43cd-b696-7ab119756b3a"}]}}}}}}}}
>
  
</StatusCodes>

---

## Variations

```mdx-code-block
import VariationsOverview from '/docs/partials/pxm/variations/variationsoverview.mdx';
import VariationsReusability from '/docs/partials/pxm/variations/variationsreusability.mdx';
import ChildProducts from '/docs/partials/pxm/variations/childproducts.mdx';
import BuildChildren from '/docs/partials/pxm/variations/buildchildproducts.mdx';
import ProductModifiers from '/docs/partials/pxm/variations/productmodifiers.mdx';
import PriceModifiers from "/docs/partials/pxm/variations/pricemodifiers.mdx";

<VariationsOverview />

### Reusability

<VariationsReusability />

### Child Products

<ChildProducts />

### Building Child Products

<BuildChildren />

### Sorting the Order of Variations and Options

The `variation_matrix` object lists the variation IDs and variation option IDs and their corresponding product IDs that are generated when the variation and variation options are built with a product. The `variation_matrix` can then be added to your catalogs.

The order of the variations in the `variation_matrix` is the order of the variations in the array when the variations were linked to the product. For example, the first variation in the `variation_matrix` corresponds to the first variation in the array, and so on. You can use the `sort_order`attribute to sort the order of your variation and variation options in the `variation_matrix` object. The sort order value is visible when you add the variations and variation options to your catalogs. You can then use the `sort_order` value to program your storefront to display the variations and variation options in the order that you want.

Add the `sort_order` attribute to the body of your request and specify a `sort_order` value. A `sort_order` value must be a number. You can specify any numbers that you want.

- 1, 2, 3, or 100, 90, 80, and so on.
- Zero or negative numbers.

You can set `sort_order` to either `null` or omit it entirely from the request if you wish to remove an existing `sort_order` attribute.

:::caution

- Commerce does not sort variations and variation options. You must program your storefront to sort the variations and variation options in the order that you want.
- You must rebuild your products for the sort order changes to take effect. See [**Build Child Products**](#build-child-products).

:::

### Product Modifiers

<ProductModifiers />

### Price Modifiers

<PriceModifiers />
```

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Delete Project Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Project Settings"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/settings"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a store setting. Organization settings cannot be deleted.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"integer","description":"The HTTP response code of the error.","examples":[400]},"code":{"type":"integer","description":"An application-specific error code.","examples":[10]},"source":{"type":"string","description":"The field that caused the validation error.","examples":["data.page_length"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":"{\n  \"errors\": [\n    {\n      \"title\": \"Unauthorized\",\n      \"status\": \"401\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"integer","description":"The HTTP response code of the error.","examples":[400]},"code":{"type":"integer","description":"An application-specific error code.","examples":[10]},"source":{"type":"string","description":"The field that caused the validation error.","examples":["data.page_length"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Get Project Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Project Settings"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/settings"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can get all of the project settings via one API call using a `client_credential` token. The response is in object format as shown in the following example.

:::note

The default `calculation_method` is `line`.

:::

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you’re sending. Set this value to `settings`.","example":"settings"},"page_length":{"type":"integer","description":" Indicates the number of results per page (max: `100`).","example":25},"list_child_products":{"type":"boolean","description":"Displays child products or not in product listings.","example":false},"additional_languages":{"description":"Represents an array of alpha2 codes for supported languages.","type":"array","items":{"type":"string"},"example":["es","fr","de"]},"calculation_method":{"type":"string","description":"Displays the method used to calculate card and order totals.","example":"line","enum":["line","simple"]},"address_mandatory_fields":{"type":"array","description":"Indicates an array of fields that are required for creating an [address](/docs/api/addresses/account-addresses).","example":["first_name","last_name","line_1","city","region","postcode","country","instructions"],"items":{"type":"string"}},"shopper_address_limit":{"type":"integer","description":"The maximum number of addresses a shopper can have per resource. API clients can only set values up to 500, for a higher limit please contact support.","example":25,"minimum":1,"maximum":25000}},"required":["type"],"title":"Settings"},{"type":"object","properties":{"id":{"description":"The unique identifier for the settings.","type":"string","example":"61daaa08-9z05-4497-b9ca-626cd0f9932b"},"include_organization_resources":{"description":"Whether to include organization resources.","type":"boolean","example":false},"cart_item_limit":{"description":"The cart item limit.","type":"integer","example":100},"custom_discount_limit":{"description":"The custom discount limit.","type":"integer","example":5},"currency_limit":{"description":"The currency limit.","type":"integer","example":10},"field_limit":{"description":"The field limit.","type":"integer","example":100},"integration_limit":{"description":"The integration limit.","type":"integer","example":100},"event_limit":{"description":"The event limit.","type":"integer","example":5},"filter_limit":{"description":"The filter limit.","type":"integer","example":10},"tax_item_limit":{"description":"The tax item limit.","type":"integer","example":5},"promotions_limit":{"description":"The promotions limit.","type":"integer","example":1000},"promotion_codes_limit":{"description":"The promotion codes limit.","type":"integer","example":1000},"page_offset_limit":{"description":"The page offset limit.","type":"integer","example":10000}}}]}},"title":"SettingsData"},{"type":"object","properties":{"meta":{"type":"object","properties":{"owner":{"type":"string","example":"store"}}}}}],"title":"SettingsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"integer","description":"The HTTP response code of the error.","examples":[400]},"code":{"type":"integer","description":"An application-specific error code.","examples":[10]},"source":{"type":"string","description":"The field that caused the validation error.","examples":["data.page_length"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":"{\n  \"errors\": [\n    {\n      \"title\": \"Unauthorized\",\n      \"status\": \"401\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"integer","description":"The HTTP response code of the error.","examples":[400]},"code":{"type":"integer","description":"An application-specific error code.","examples":[10]},"source":{"type":"string","description":"The field that caused the validation error.","examples":["data.page_length"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Update Project Settings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Project Settings"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/settings"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can use the Settings endpoint to update your project settings at any time. These global settings take immediate effect.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you’re sending. Set this value to `settings`.","example":"settings"},"page_length":{"type":"integer","description":" Indicates the number of results per page (max: `100`).","example":25},"list_child_products":{"type":"boolean","description":"Displays child products or not in product listings.","example":false},"additional_languages":{"description":"Represents an array of alpha2 codes for supported languages.","type":"array","items":{"type":"string"},"example":["es","fr","de"]},"calculation_method":{"type":"string","description":"Displays the method used to calculate card and order totals.","example":"line","enum":["line","simple"]},"address_mandatory_fields":{"type":"array","description":"Indicates an array of fields that are required for creating an [address](/docs/api/addresses/account-addresses).","example":["first_name","last_name","line_1","city","region","postcode","country","instructions"],"items":{"type":"string"}},"shopper_address_limit":{"type":"integer","description":"The maximum number of addresses a shopper can have per resource. API clients can only set values up to 500, for a higher limit please contact support.","example":25,"minimum":1,"maximum":25000}},"required":["type"],"title":"Settings"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Describes the type of request payload you’re sending. Set this value to `settings`.","example":"settings"},"page_length":{"type":"integer","description":" Indicates the number of results per page (max: `100`).","example":25},"list_child_products":{"type":"boolean","description":"Displays child products or not in product listings.","example":false},"additional_languages":{"description":"Represents an array of alpha2 codes for supported languages.","type":"array","items":{"type":"string"},"example":["es","fr","de"]},"calculation_method":{"type":"string","description":"Displays the method used to calculate card and order totals.","example":"line","enum":["line","simple"]},"address_mandatory_fields":{"type":"array","description":"Indicates an array of fields that are required for creating an [address](/docs/api/addresses/account-addresses).","example":["first_name","last_name","line_1","city","region","postcode","country","instructions"],"items":{"type":"string"}},"shopper_address_limit":{"type":"integer","description":"The maximum number of addresses a shopper can have per resource. API clients can only set values up to 500, for a higher limit please contact support.","example":25,"minimum":1,"maximum":25000}},"required":["type"],"title":"Settings"},{"type":"object","properties":{"id":{"description":"The unique identifier for the settings.","type":"string","example":"61daaa08-9z05-4497-b9ca-626cd0f9932b"},"include_organization_resources":{"description":"Whether to include organization resources.","type":"boolean","example":false},"cart_item_limit":{"description":"The cart item limit.","type":"integer","example":100},"custom_discount_limit":{"description":"The custom discount limit.","type":"integer","example":5},"currency_limit":{"description":"The currency limit.","type":"integer","example":10},"field_limit":{"description":"The field limit.","type":"integer","example":100},"integration_limit":{"description":"The integration limit.","type":"integer","example":100},"event_limit":{"description":"The event limit.","type":"integer","example":5},"filter_limit":{"description":"The filter limit.","type":"integer","example":10},"tax_item_limit":{"description":"The tax item limit.","type":"integer","example":5},"promotions_limit":{"description":"The promotions limit.","type":"integer","example":1000},"promotion_codes_limit":{"description":"The promotion codes limit.","type":"integer","example":1000},"page_offset_limit":{"description":"The page offset limit.","type":"integer","example":10000}}}]}},"title":"SettingsData"},{"type":"object","properties":{"meta":{"type":"object","properties":{"owner":{"type":"string","example":"store"}}}}}],"title":"SettingsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"integer","description":"The HTTP response code of the error.","examples":[400]},"code":{"type":"integer","description":"An application-specific error code.","examples":[10]},"source":{"type":"string","description":"The field that caused the validation error.","examples":["data.page_length"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":"{\n  \"errors\": [\n    {\n      \"title\": \"enum\",\n      \"source\": \"data.type\",\n      \"detail\": \"data.type must be one of the following: \\\"settings\\\"\"\n    }\n  ]\n}\n"}}}}},"default":{"description":"Internal server error.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"integer","description":"The HTTP response code of the error.","examples":[400]},"code":{"type":"integer","description":"An application-specific error code.","examples":[10]},"source":{"type":"string","description":"The field that caused the validation error.","examples":["data.page_length"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":"{\n  \"errors\": [\n    {\n      \"title\": \"Internal Server Error\",\n      \"status\": \"500\",\n      \"detail\": \"there was a problem processing your request\"\n    }\n  ]\n}\n"}}}}}}}
>
  
</StatusCodes>

---

## Settings Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/settings/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Settings Introduction"}
>
</Heading>

The Settings API allow you to configure global settings for your project. You can define:

- [page length when paginating results](/docs/api/settings/settings-introduction#page-length)
- [the calculation method you want to use for cart and order totals](/docs/api/settings/settings-introduction#calculation-method)
- [mandatory address fields](/docs/api/settings/settings-introduction#address-mandatory-fields)
- [shopper address limit](/docs/api/settings/settings-introduction#shopper-address-limit)
- [readonly store settings for internal stores](/docs/api/settings/settings-introduction#readonly-settings)

### Page Length

This defines the number of results per page when paginating results (max: 100).

| Name          | Type      | Default | Max |
|--------------|-----------|--------- |-----|
| `page_length` | `integer` | 25       | 100 |

For more information on pagination including a list of which resources support pagination, see [Pagination](/guides/Getting-Started/pagination).

### Calculation Method

This option defines the method used to calculate cart and order totals. Currently there are two methods: `simple` and `line`.

The `simple` method is our previous method for calculating cart and order totals which focuses on the total value of the cart. This should only be used in the case where Composable Commerce is not used for tax calculations. The `line` method treats each line item individually resulting in more accurate figures after taxes and promotions are applied.

| Name         | Type      | Value |
|--------------|-----------|-------|
| `calculation_method` | `string` | `line`   |
| `calculation_method` | `string` | `simple` |

:::note

- For stores created since February 2020, `line` is the default calculation method. Stores created before February 2020 use `simple` as their calculation method.
- Line-item discount promotions, such as item percent discount and item fixed discount, are only supported by the line calculation method. For more information, see [Promotions Standard](/docs/api/promotions/promotions-standard-introduction).

:::

### Address Mandatory Fields

You can create an address to associate with an account in your storefront. This defines the address fields that you can use when creating an address in Commerce Manager. For more information, see [Addresses](/docs/api/addresses/addresses-introduction).

Address fields can be required or optional. You can choose which optional address fields to use in your address, depending on your requirements. To change which fields are mandatory for creating an address, see [Update Settings](/docs/api/settings/put-v-2-settings). Changing the mandatory fields does not impact the addresses of customers made before the change.

The following table describes the address fields, their type and whether they are required by default.

| Name | Type | Required |
| :--- | :--- |:---------|
| `type` |`string` | Default  |
| `first_name` |`string` | Default  |
| `last_name` |`string` | Default  |
| `name` |`string` | Optional |
| `phone_number` |`string` | Optional |
| `instructions` |`string` | Optional |
| `company_name` |`string` | Optional |
| `line_1` |`string` | Default  |
| `line_2` |`string` | Optional |
| `city` |`string` | Optional |
| `county` |`string` | Default  |
| `region` |`string` | Optional |
| `postcode` |`string` | Default  |
| `country` |`string` | Default  |

### Shopper Address Limit

This defines the maximum number of addresses a shopper can create per resource (account). This helps prevent abuse and maintains database performance.

| Name          | Type      | Default | Min | Max   |
|--------------|-----------|---------|-----|-------|
| `shopper_address_limit` | `integer` | 25  | 1   | 25000 |

:::note
Only values up to 500 can be set by callers. Please [contact Support](https://support.elasticpath.com/hc/en-us#composable_commerce) if you require a higher limit. 
:::

### Readonly Settings

For internal store configurations, read-only settings are used and updating these settings fails without returning any error.

:::note

- Refer to the [Performance](/guides/Getting-Started/pagination#performance) section in the Pagination documentation, which outlines patterns for retrieving all documents without using a higher page offset limit.
- To change any predefined configuration, contact [Elastic Path support team](https://support.elasticpath.com/hc/en-us).

:::

| Name                    | Type      | Default                                              |
|:------------------------|:----------|:-----------------------------------------------------|
| `currency_limit`        | `integer` | `10`                                                 |
| `field_limit`           | `integer` | `100`                                                |
| `integration_limit`     | `integer` | `100`                                                |
| `event_limit`           | `integer` | `5`                                                  |
| `filter_limit`          | `integer` | `10`                                                 |
| `tax_item_limit`        | `integer` | `5`                                                  |
| `promotions_limit`      | `integer` | `1000`                                               |
| `promotion_codes_limit` | `integer` | `1000`                                               |
| `page_offset_limit`     | `integer` | `10000`                                              |

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"BearerToken"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## Settings

The Settings API allow you to configure global settings for your project.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Authentication Realms

An authentication realm is a container that consists of the following:

  - Users -  Represented by [User Authentication Info](/docs/api/single-sign-on/user-authentication-infos) objects
  - Authentication profiles - Ways for the users to authenticate, such as one or more [OpenID Connect Profiles](/docs/api/single-sign-on/oidc-profiles) or [Password Profiles](/docs/api/single-sign-on/password-profiles)
  - Mappings between users and authentication profiles - [User Authentication OpenID Connect Profile Info](/docs/api/single-sign-on/user-authentication-oidc-profile-infos) or [User Authentication Password Profile Infos](/docs/api/single-sign-on/user-authentication-password-profile-infos)

Here's a domain diagram showing these relationships
![authentication realm](/assets/authentication-realm-domain.png)

Composable Commerce comes with three per-store pre-set realms:
  - Buyer Organization. For customers: users who buy products from your store.
  - Merchant Organization. For administrators: users who log in to Commerce Manager to modify the store’s settings or catalog.
  - Account Management Realm. For account members: users who buy products from your store on behalf of accounts. Password profiles are only available for account management realm.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Delete OIDC Profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete OIDC Profile"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/authentication-realms/{realmId}/oidc-profiles/{profileId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a specific OIDC profile by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","description":"The ID of the OIDC profile.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete Password Profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Password Profile"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/authentication-realms/{realmId}/password-profiles/{profileId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a specific password profile by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","description":"The ID of the password profile.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete User Authentication OIDC Profile Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete User Authentication OIDC Profile Info"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-oidc-profile-info/{oidcInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete specific OIDC profile information by ID for a user.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"oidcInfoId","in":"path","description":"The ID of the OIDC profile info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete User Authentication Password Profile Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete User Authentication Password Profile Info"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-password-profile-info/{passwordProfileInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete specific password profile information by ID for a user.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"passwordProfileInfoId","in":"path","description":"The ID of the password profile info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete User Authentication Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete User Authentication Info"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete specific user authentication information by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"No Content"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Initiate OIDC Login

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Initiate OIDC Login"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/oidc-idp/login/stores/{storeId}/authentication-realms/{realmId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Initiate the OIDC login flow for a specific store and authentication realm
::: note This is not an **API Endpoint**, but the [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) of the OpenID Connect Authentication Flow.
To initiate an OpenID Connect authentication you must change the location in the Browser to this URL, not call it asynchronously. :::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"storeId","in":"path","description":"The ID of the store.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"client_id","in":"query","description":"The Client ID, for Account Management Authentication see the `meta.client_id` field on [Account Authentication Settings](/docs/api/accounts/get-v-2-settings-account-authentication).","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","description":"Redirection URI to which the response will be sent. Must exactly match a pre-registered redirect URI for the client in the `redirect_uris` of the [Authentication Realm](/docs/api/single-sign-on/get-v-2-authentication-realms-realm-id).","required":true,"schema":{"type":"string","format":"uri"}},{"name":"response_type","in":"query","description":"OIDC/OAuth 2.0 response type, this must be \"code\" in Commerce.","required":true,"schema":{"type":"string","const":"code"}},{"name":"scope","in":"query","description":"Space-delimited list of scopes. Must include \"openid\", \"email\", and \"name\".","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","description":"Opaque value used to maintain state between the request and the callback. Helps prevent CSRF.","required":true,"schema":{"type":"string","maxLength":2048}},{"name":"code_challenge_method","in":"query","description":"[Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) transformation method that was used to derive code_challenge.","required":true,"schema":{"type":"string","enum":["S256","plain"]},"example":"S256"},{"name":"code_challenge","in":"query","description":"[Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636) Code Challenge.","required":true,"schema":{"type":"string"}},{"name":"prompt","in":"query","description":"Space-delimited, case-sensitive list that specifies whether the Authorization Server prompts the End-User for re-authentication and consent.  This value is passed to the configured IdP. See [Section 3.1.2.1. Authentication Request - OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).","required":false,"schema":{"type":"string"}},{"name":"display","in":"query","description":"ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface. This value is passed to the configured IdP. See [Section 3.1.2.1. Authentication Request - OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).","required":false,"schema":{"type":"string"}},{"name":"ui_locales","in":"query","description":"End-User's preferred languages and scripts for the user interface, represented as space-separated list of BCP47 language tag values. This value is forwarded to the configured IdP.  See [Section 3.1.2.1. Authentication Request - OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).","required":false,"schema":{"type":"string"},"example":"fr-CA fr en"},{"name":"elasticpath_commerce_cloud_profile_id","in":"query","description":"Selects the specific OIDC Profile within the realm to use for authentication.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"ep_report_callback_replay_error","in":"query","description":"Custom boolean flag. If true, if the user attempts to hit back in their browser, we will redirect them back to the store front","required":false,"schema":{"type":"boolean"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"303":{"description":"See Other - Redirects to the IdP provider for authentication","headers":{"Location":{"description":"The URL of the IdP provider to redirect to","schema":{"type":"string","format":"uri"}}}},"307":{"description":"Temporary Redirect - Redirects the user back to the caller.","headers":{"Location":{"description":"The location to redirect to, typically the store front.","schema":{"type":"string","format":"uri"}}}},"400":{"description":"In some cases the OAuth 2.0 specification does not permit us to redirect the user back to the caller, in which case they will see a 4xx.\n","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"OAuth 2.0 error code"},"errorDescription":{"type":"string","description":"Human-readable error description (camelCase)"},"error_description":{"type":"string","description":"Human-readable error description (snake_case, OAuth 2.0 standard)"}},"required":["error"]},"examples":{"invalid_client":{"summary":"Invalid client_id","value":{"error":"invalid_request","errorDescription":"The field [client_id] with value [unknownClient] is invalid.","error_description":"The field [client_id] with value [unknownClient] is invalid."}}}}}}}}
>
  
</StatusCodes>

---

## OpenID Connect Discovery

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"OpenID Connect Discovery"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/oidc-idp/stores/{storeId}/authentication-realms/{realmId}/.well-known/openid-configuration"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the OpenID Connect discovery document for the authentication realm.
This endpoint provides metadata about the OIDC provider's configuration, including endpoints, supported features, and capabilities. Some libraries might require an OIDC discovery document in order to work.
For more information see [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"storeId","in":"path","description":"The ID of the store.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"elasticpath_commerce_cloud_profile_id","in":"query","description":"The ID of the [OIDC profile](/docs/api/single-sign-on/oidc-profiles) that you would like to authenticate with","required":false,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK - OpenID Connect discovery document","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string","format":"uri","description":"The issuer identifier for this OIDC provider"},"authorization_endpoint":{"type":"string","format":"uri","description":"URL of the authorization endpoint"},"token_endpoint":{"type":"string","format":"uri","description":"URL of the token endpoint, note that this endpoint is not public, and clients will not call it."},"jwks_uri":{"type":"string","format":"uri","description":"URL of the JSON Web Key Set document"},"response_types_supported":{"type":"array","items":{"type":"string"},"description":"List of OAuth 2.0 response_type values supported"},"subject_types_supported":{"type":"array","items":{"type":"string"},"description":"List of subject identifier types supported"},"id_token_signing_alg_values_supported":{"type":"array","items":{"type":"string"},"description":"List of JWS signing algorithms supported for ID Tokens"},"scopes_supported":{"type":"array","items":{"type":"string"},"description":"List of OAuth 2.0 scope values supported"},"token_endpoint_auth_methods_supported":{"type":"string","description":"Authentication methods supported by the token endpoint"}},"required":["issuer","authorization_endpoint","token_endpoint","jwks_uri","response_types_supported","subject_types_supported","id_token_signing_alg_values_supported"]},"examples":{"discovery_document":{"summary":"OpenID Connect discovery document","value":{"authorization_endpoint":"http://euwest.api.elasticpath.com/oidc-idp/login/stores/88888888-4444-4333-8333-111111111111/authentication-realms/45928070-44a6-448b-8246-a85aa35320af","id_token_signing_alg_values_supported":["RS256"],"issuer":"http://euwest.api.elasticpath.com/oidc-idp/stores/88888888-4444-4333-8333-111111111111/authentication-realms/45928070-44a6-448b-8246-a85aa35320af","jwks_uri":"http://euwest.api.elasticpath.com/oidc-idp/.well-known/jwks.json","response_types_supported":["code"],"scopes_supported":["profile","openid","email"],"subject_types_supported":["public"],"token_endpoint":"http://euwest.api.elasticpath.com/oidc-idp/token/stores/88888888-4444-4333-8333-111111111111/authentication-realms/45928070-44a6-448b-8246-a85aa35320af","token_endpoint_auth_methods_supported":"client_secret_basic"}}}}}}}}
>
  
</StatusCodes>

---

## Get OIDC Profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get OIDC Profile"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/oidc-profiles/{profileId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve a specific OIDC profile by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","description":"The ID of the OIDC profile.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `oidc-profile`.","const":"oidc-profile"},"name":{"type":"string","description":"Specifies the name of the OIDC profile.","example":"my-oidc-profile"},"discovery_url":{"type":"string","description":"The OIDC discovery URL.","format":"uri","example":"https://example.com/.well-known/openid_configuration"},"client_id":{"type":"string","description":"The client ID for the OpenID Provider.","example":"my-client-id"},"client_secret":{"type":"string","description":"The client secret for the OpenID Provider.","example":"my-client-secret"}},"required":["type","name"],"title":"OidcProfile"},{"type":"object","properties":{"id":{"description":"The unique identifier for an OIDC Profile.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2025-09-08T20:58:56.355Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2025-09-08T20:58:56.355Z"},"issuer":{"description":"The OIDC issuer URL.","type":"string","format":"uri","example":"https://test.issuer.com"}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/oidc-profiles/abc123"},"authorization-endpoint":{"description":"The authorization endpoint URL.","type":"string","format":"uri"},"callback-endpoint":{"description":"The callback endpoint URL.","type":"string","format":"uri"},"client-discovery-url":{"description":"The client discovery URL.","type":"string","format":"uri"}}}}}],"title":"OidcProfileResponse"},"links":{"allOf":[{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"},{"type":"object","properties":{"authorization-endpoint":{"description":"The link that front-end applications should use to authenticate the OpenID Connect profile. The front-end application is responsible for appending all of the [required parameters](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) to the request. The endpoint also forwards some optional parameters, `display`, `prompt` and `ui_locales` to the configured Identity Provider. These parameters allow you to control the behavior of the authentication process on the Identity Provider. Additionally the query parameter `ep_report_callback_replay_error` can be set to `true` in which case if the user revisits the `callback-endpoint` multiple times (e.g., if they hit their Back button), we will redirect the user back to the front end with an [Authentication error response](https://openid.net/specs/openid-connect-core-1_0.html#AuthError) of `callback_replay`.","type":"string","format":"uri"},"callback-endpoint":{"description":"The link that should be supplied as the callback URL to the upstream authentication provider.","type":"string","format":"uri"},"client-discovery-url":{"description":"The link to the [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) document for this provider, see [here](/docs/api/single-sign-on/get-oidc-idp-stores-store-id-authentication-realms-realm-id-well-known-openid-configuration).","type":"string","format":"uri"}}}],"title":"OidcProfileLinks"}}},"examples":{"get_oidc_profile":{"summary":"OIDC profile","value":{"data":{"id":"c8849022-c9c6-4888-9ca8-2bb78f445fb0","type":"oidc-profile","name":"Google","issuer":"https://accounts.google.com","client_id":"google-client-id"},"links":{"self":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/oidc-profiles/c8849022-c9c6-4888-9ca8-2bb78f445fb0"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get OIDC Profiles

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get OIDC Profiles"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/oidc-profiles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve OIDC profiles for the specified authentication realm.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"maximum":100,"default":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"default":0}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `oidc-profile`.","const":"oidc-profile"},"name":{"type":"string","description":"Specifies the name of the OIDC profile.","example":"my-oidc-profile"},"discovery_url":{"type":"string","description":"The OIDC discovery URL.","format":"uri","example":"https://example.com/.well-known/openid_configuration"},"client_id":{"type":"string","description":"The client ID for the OpenID Provider.","example":"my-client-id"},"client_secret":{"type":"string","description":"The client secret for the OpenID Provider.","example":"my-client-secret"}},"required":["type","name"],"title":"OidcProfile"},{"type":"object","properties":{"id":{"description":"The unique identifier for an OIDC Profile.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2025-09-08T20:58:56.355Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2025-09-08T20:58:56.355Z"},"issuer":{"description":"The OIDC issuer URL.","type":"string","format":"uri","example":"https://test.issuer.com"}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/oidc-profiles/abc123"},"authorization-endpoint":{"description":"The authorization endpoint URL.","type":"string","format":"uri"},"callback-endpoint":{"description":"The callback endpoint URL.","type":"string","format":"uri"},"client-discovery-url":{"description":"The client discovery URL.","type":"string","format":"uri"}}}}}],"title":"OidcProfileResponse"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"The current page of data."},"first":{"type":["string","null"],"format":"uri","description":"The first page of data."},"last":{"type":["string","null"],"format":"uri","description":"The last page of data."},"next":{"type":["string","null"],"format":"uri","description":"The next page of data."},"prev":{"type":["string","null"],"format":"uri","description":"The previous page of data."},"self":{"type":"string","format":"uri","description":"The current resource URL."}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"The current page number.","example":1},"limit":{"type":"integer","description":"The number of items per page.","example":25},"offset":{"type":"integer","description":"The number of items to offset by.","example":0},"total":{"type":"integer","description":"The total number of pages.","example":1}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}}}},"title":"PaginationMeta"}}},"examples":{"list_oidc_profiles":{"summary":"List of OIDC profiles","value":{"data":[{"id":"c8849022-c9c6-4888-9ca8-2bb78f445fb0","type":"oidc-profile","name":"Google","issuer":"https://accounts.google.com","client_id":"google-client-id"},{"id":"21be087e-faa6-41fc-9b51-6763a363ec2d","type":"oidc-profile","name":"Apple","issuer":"https://appleid.apple.com","client_id":"apple-client-id"}],"meta":{"results":{"total":2},"page":{"limit":25,"offset":0}},"links":{"current":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/oidc-profiles?page%5Boffset%5D=0&page%5Blimit%5D=25","first":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/oidc-profiles?page%5Boffset%5D=0&page%5Blimit%5D=25","last":null,"next":null,"prev":null}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Password Profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Password Profile"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/password-profiles/{profileId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve a specific password profile by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","description":"The ID of the password profile.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `password_profile`.","const":"password_profile"},"name":{"type":"string","description":"Specifies the name of the password profile.","example":"my-password-profile"},"username_format":{"type":"string","description":"The format the `username` field must be in when creating or updating a [User Authentication Password Profile Info](/docs/api/single-sign-on/post-v-2-authentication-realms-realm-id-user-authentication-info-user-auth-info-id-user-authentication-password-profile-info). You can change the `username_format` setting, however, the changes apply only to the users created or updated after changing this setting. The new setting does not change the `username_format` for existing users.","enum":["email","any"],"x-enumDescriptions":{"email":"The `username` must be a valid e-mail.","any":"The `username` can be any string."},"example":"email"},"enable_one_time_password_token":{"type":"boolean","description":"This enables one time password token requests and events for authentication. This feature is disabled by default.","example":true}},"required":["type","name"],"title":"PasswordProfile"},{"type":"object","properties":{"id":{"description":"The unique identifier for a Password Profile.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this password profile.","type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/password-profiles/abc123"}}}}}],"title":"PasswordProfileResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}},"examples":{"get_password_profile":{"summary":"Password profile","value":{"data":{"id":"a2f6d4c0-1d2b-4b3a-9e5a-2f4b1c7d8e9f","type":"password_profile","name":"Default Passwords"},"links":{"self":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/password-profiles/a2f6d4c0-1d2b-4b3a-9e5a-2f4b1c7d8e9f"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get Password Profiles

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Password Profiles"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/password-profiles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve password profiles for the specified authentication realm.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"maximum":100,"default":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"default":0}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `password_profile`.","const":"password_profile"},"name":{"type":"string","description":"Specifies the name of the password profile.","example":"my-password-profile"},"username_format":{"type":"string","description":"The format the `username` field must be in when creating or updating a [User Authentication Password Profile Info](/docs/api/single-sign-on/post-v-2-authentication-realms-realm-id-user-authentication-info-user-auth-info-id-user-authentication-password-profile-info). You can change the `username_format` setting, however, the changes apply only to the users created or updated after changing this setting. The new setting does not change the `username_format` for existing users.","enum":["email","any"],"x-enumDescriptions":{"email":"The `username` must be a valid e-mail.","any":"The `username` can be any string."},"example":"email"},"enable_one_time_password_token":{"type":"boolean","description":"This enables one time password token requests and events for authentication. This feature is disabled by default.","example":true}},"required":["type","name"],"title":"PasswordProfile"},{"type":"object","properties":{"id":{"description":"The unique identifier for a Password Profile.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this password profile.","type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/password-profiles/abc123"}}}}}],"title":"PasswordProfileResponse"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"The current page of data."},"first":{"type":["string","null"],"format":"uri","description":"The first page of data."},"last":{"type":["string","null"],"format":"uri","description":"The last page of data."},"next":{"type":["string","null"],"format":"uri","description":"The next page of data."},"prev":{"type":["string","null"],"format":"uri","description":"The previous page of data."},"self":{"type":"string","format":"uri","description":"The current resource URL."}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"The current page number.","example":1},"limit":{"type":"integer","description":"The number of items per page.","example":25},"offset":{"type":"integer","description":"The number of items to offset by.","example":0},"total":{"type":"integer","description":"The total number of pages.","example":1}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}}}},"title":"PaginationMeta"}}},"examples":{"list_password_profiles":{"summary":"List of password profiles","value":{"data":[{"id":"a2f6d4c0-1d2b-4b3a-9e5a-2f4b1c7d8e9f","type":"password_profile","name":"Default Passwords","require_uppercase":true,"require_numbers":true,"min_length":10},{"id":"b3e7f5a1-2c3d-4e4b-8f6a-3e5c2d8f9a0b","type":"password_profile","name":"Impersonation Profile","require_uppercase":false,"require_numbers":false,"min_length":8}],"meta":{"results":{"total":2},"page":{"limit":25,"offset":0}},"links":{"current":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/password-profiles?page%5Boffset%5D=0&page%5Blimit%5D=25","first":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/password-profiles?page%5Boffset%5D=0&page%5Blimit%5D=25","last":null,"next":null,"prev":null}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get User Authentication OIDC Profile Info by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get User Authentication OIDC Profile Info by ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-oidc-profile-info/{oidcInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve specific OIDC profile information by ID for a user.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"oidcInfoId","in":"path","description":"The ID of the OIDC profile info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_oidc_profile_info`.","const":"user_authentication_oidc_profile_info"},"oidc_profile_id":{"type":"string","description":"The ID of the associated [OIDC profile](/docs/authentication/single-sign-on/openid-connect-profiles-api/openid-connect-profiles-api-overview).","format":"uuid","example":"f1a2932f-3579-46f0-92e1-a4a80cd26e37"},"subject":{"type":"string","description":"The identifier within the issuer for the `user-authentication-info` object. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","example":"subject-123"},"issuer":{"type":"string","description":"The identifier for the issuer of the ID Token. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","format":"uri","example":"https://test.issuer.com"}},"required":["type","oidc_profile_id"],"title":"UserAuthenticationOidcProfileInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication OIDC Profile Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123/user-authentication-oidc-profile-info/def456"}}}}}],"title":"UserAuthenticationOidcProfileInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}},"examples":{"get_user_auth_oidc_profile_info":{"summary":"OIDC Profile Info for a user","value":{"data":{"id":"f1a2b3c4-d5e6-47f8-9a0b-c1d2e3f4a5b6","type":"user_authentication_oidc_profile_info","oidc_profile_id":"c8849022-c9c6-4888-9ca8-2bb78f445fb0","subject":"subject-123","issuer":"https://accounts.google.com"},"links":{"self":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info/40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c/user-authentication-oidc-profile-info/f1a2b3c4-d5e6-47f8-9a0b-c1d2e3f4a5b6"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get User Authentication OIDC Profile Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get User Authentication OIDC Profile Info"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-oidc-profile-info"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve OIDC profile information for a specific user authentication info.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"maximum":100,"default":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"default":0}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_oidc_profile_info`.","const":"user_authentication_oidc_profile_info"},"oidc_profile_id":{"type":"string","description":"The ID of the associated [OIDC profile](/docs/authentication/single-sign-on/openid-connect-profiles-api/openid-connect-profiles-api-overview).","format":"uuid","example":"f1a2932f-3579-46f0-92e1-a4a80cd26e37"},"subject":{"type":"string","description":"The identifier within the issuer for the `user-authentication-info` object. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","example":"subject-123"},"issuer":{"type":"string","description":"The identifier for the issuer of the ID Token. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","format":"uri","example":"https://test.issuer.com"}},"required":["type","oidc_profile_id"],"title":"UserAuthenticationOidcProfileInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication OIDC Profile Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123/user-authentication-oidc-profile-info/def456"}}}}}],"title":"UserAuthenticationOidcProfileInfoResponse"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"The current page of data."},"first":{"type":["string","null"],"format":"uri","description":"The first page of data."},"last":{"type":["string","null"],"format":"uri","description":"The last page of data."},"next":{"type":["string","null"],"format":"uri","description":"The next page of data."},"prev":{"type":["string","null"],"format":"uri","description":"The previous page of data."},"self":{"type":"string","format":"uri","description":"The current resource URL."}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"The current page number.","example":1},"limit":{"type":"integer","description":"The number of items per page.","example":25},"offset":{"type":"integer","description":"The number of items to offset by.","example":0},"total":{"type":"integer","description":"The total number of pages.","example":1}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}}}},"title":"PaginationMeta"}}},"examples":{"list_user_auth_oidc_profile_info":{"summary":"List of OIDC Profile Info for a user","value":{"data":[{"id":"f1a2b3c4-d5e6-47f8-9a0b-c1d2e3f4a5b6","type":"user_authentication_oidc_profile_info","oidc_profile_id":"c8849022-c9c6-4888-9ca8-2bb78f445fb0","subject":"subject-123","issuer":"https://accounts.google.com"},{"id":"0a1b2c3d-4e5f-6071-8a9b-bc0d1e2f3a4b","type":"user_authentication_oidc_profile_info","oidc_profile_id":"21be087e-faa6-41fc-9b51-6763a363ec2d","subject":"subject-456","issuer":"https://appleid.apple.com"}],"meta":{"results":{"total":2},"page":{"limit":25,"offset":0}},"links":{"current":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info/40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c/user-authentication-oidc-profile-info?page%5Boffset%5D=0&page%5Blimit%5D=25","first":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info/40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c/user-authentication-oidc-profile-info?page%5Boffset%5D=0&page%5Blimit%5D=25","last":null,"next":null,"prev":null}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get User Authentication Password Profile Info by ID

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get User Authentication Password Profile Info by ID"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-password-profile-info/{passwordProfileInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve specific password profile information by ID for a user.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"passwordProfileInfoId","in":"path","description":"The ID of the password profile info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_password_profile_info`.","const":"user_authentication_password_profile_info"},"username":{"type":"string","description":"The username used to authenticate.","example":"uauppinamepestupdate@test.com"},"password_profile_id":{"type":"string","description":"The ID of the associated password profile.","format":"uuid","example":"767e6763-014e-4b6e-8a0e-59b863ab3262"}},"required":["type","username","password_profile_id"],"title":"UserAuthenticationPasswordProfileInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication Password Profile Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123/user-authentication-password-profile-info/def456"}}}}}],"title":"UserAuthenticationPasswordProfileInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}},"examples":{"get_user_auth_password_profile_info":{"summary":"Password Profile Info for a user","value":{"data":{"id":"9f8e7d6c-5b4a-3a2f-1e0d-c9b8a7f6e5d4","type":"user_authentication_password_profile_info","username":"uauppinamepestupdate@test.com","password_profile_id":"a2f6d4c0-1d2b-4b3a-9e5a-2f4b1c7d8e9f"},"links":{"self":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info/40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c/user-authentication-password-profile-info/9f8e7d6c-5b4a-3a2f-1e0d-c9b8a7f6e5d4"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get User Authentication Password Profile Info List

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get User Authentication Password Profile Info List"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-password-profile-info"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve a list of password profile information for a user.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"maximum":100,"default":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"default":0}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_password_profile_info`.","const":"user_authentication_password_profile_info"},"username":{"type":"string","description":"The username used to authenticate.","example":"uauppinamepestupdate@test.com"},"password_profile_id":{"type":"string","description":"The ID of the associated password profile.","format":"uuid","example":"767e6763-014e-4b6e-8a0e-59b863ab3262"}},"required":["type","username","password_profile_id"],"title":"UserAuthenticationPasswordProfileInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication Password Profile Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123/user-authentication-password-profile-info/def456"}}}}}],"title":"UserAuthenticationPasswordProfileInfoResponse"}},"links":{"type":"object","properties":{"current":{"type":"string","format":"uri","description":"The current page of data."},"first":{"type":["string","null"],"format":"uri","description":"The first page of data."},"last":{"type":["string","null"],"format":"uri","description":"The last page of data."},"next":{"type":["string","null"],"format":"uri","description":"The next page of data."},"prev":{"type":["string","null"],"format":"uri","description":"The previous page of data."},"self":{"type":"string","format":"uri","description":"The current resource URL."}},"title":"PaginationLinks"},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"current":{"type":"integer","description":"The current page number.","example":1},"limit":{"type":"integer","description":"The number of items per page.","example":25},"offset":{"type":"integer","description":"The number of items to offset by.","example":0},"total":{"type":"integer","description":"The total number of pages.","example":1}}},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}}}},"title":"PaginationMeta"}}},"examples":{"list_user_auth_password_profile_info":{"summary":"List of Password Profile Info for a user","value":{"data":[{"id":"9f8e7d6c-5b4a-3a2f-1e0d-c9b8a7f6e5d4","type":"user_authentication_password_profile_info","username":"uauppinamepestupdate@test.com","password_profile_id":"a2f6d4c0-1d2b-4b3a-9e5a-2f4b1c7d8e9f"},{"id":"0c9b8a7f-6e5d-4c3b-2a1f-0e9d8c7b6a5f","type":"user_authentication_password_profile_info","username":"another.user@example.com","password_profile_id":"b3e7f5a1-2c3d-4e4b-8f6a-3e5c2d8f9a0b"}],"meta":{"results":{"total":2},"page":{"limit":25,"offset":0}},"links":{"current":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info/40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c/user-authentication-password-profile-info?page%5Boffset%5D=0&page%5Blimit%5D=25","first":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info/40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c/user-authentication-password-profile-info?page%5Boffset%5D=0&page%5Blimit%5D=25","last":null,"next":null,"prev":null}}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get User Authentication Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get User Authentication Info"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve specific user authentication information by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_info`.","const":"user_authentication_info"},"name":{"type":"string","description":"Specifies the name of the user.","example":"Ron Swanson"},"given_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ron"},"family_name":{"type":["string","null"],"description":"Specifies the family name of the user.","example":"Swanson"},"middle_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ulysses"},"email":{"type":"string","description":"Specifies the email address of the user.","format":"email","example":"ron@swanson.com"}},"required":["type","name","email"],"title":"UserAuthenticationInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2025-09-08T20:29:42.282Z"},"updated_at":{"description":"The last updated date of this `user-authentication-info` object. This value also changes if subresources such as the `user-authentication-oidc-profile-info`, or `user-authentication-password-profile-info` change.The last updated date of this `user-authentication-info` object. This value also changes if subresources such as the `user-authentication-oidc-profile-info`, or `user-authentication-password-profile-info` change.","type":"string","format":"date-time","example":"2025-09-08T20:29:42.282Z"},"creation_status":{"description":"The creation status of the user authentication info.","type":"string","enum":["COMPLETE","IN_PROGRESS"],"x-enumDescriptions":{"COMPLETED":"The user authentication info has been created successfully.","IN_PROGRESS":"The creation of the user authentication info is in progress (this can happen in some edge cases, if for instance the user presses refresh while signing in for the first time). Occasionally these users may be rolled back by the system."},"example":"COMPLETE"}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123"}}}}}],"title":"UserAuthenticationInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}},"examples":{"get_user_authentication_info":{"summary":"User authentication info","value":{"data":{"id":"40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c","type":"user_authentication_info","name":"Jane Doe","email":"jane.doe@example.com"},"links":{"self":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info/40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get User Authentication Info List

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get User Authentication Info List"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve user authentication information for the specified authentication realm.
### Filtering

    The following operators and attributes are available for
    [filtering](/guides/Getting-Started/filtering) unassigned account members.

    | Operator | Description   |
    | :------- |:--------------------------------------------------------------------------------------------------- |
    | `eq`     | Matches record where the field matches the value (case insensitive) |
    | `ge`  | Matches results where the value is greater than or equal to the operand |
    | `gt`  | Matches results where the value is greater than the operand |
    | `le`  | Matches results where the value is less than or equal to the operand |
    | `lt`  | Matches results where the value is less than the operand |
    | `in`  | Matches results where the value is in one of a set of values |
    | `ilike`  | Checks whether the operand contains the specified string. You can use wildcard characters at the start or end. (Case Insensitive) |
    | `is_null`  | Matches records where the field is null. |

    | Attribute | Type     | Operator      | Example
    | :-------- | :------- | :------------ | :---------------------------------   |
    | `email`   | `string` | `eq`,`ilike` | `eq(email,ronswanson@example.com)`   |
    | `name`    | `string` | `eq`,`ilike` | `ilike(name,*swan*)`       |
    | `created_at`    | `string` | `lt`, `le`, `eq`, `gt`, `ge` | `lt(created_at,"2025-09-10T22:08:47.992Z")`       |
    | `updated_at`    | `string` | `lt`, `le`, `eq`, `gt`, `ge` | `gt(updated_at,"2025-09-10T22:08:47.992Z")`       |
    | `given_name`    | `string` | `eq`,`ilike`,`is_null`  | `is_null('given_name')`       |
    | `middle_name`    | `string` | `eq`,`ilike`,`is_null`  | `is_null('middle_name')`       |
    | `family_name`    | `string` | `eq`,`ilike`,`is_null`  | `is_null('family_name')`       |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"maximum":100,"default":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"default":0}},{"name":"filter","in":"query","description":"Specifies the filter attributes.","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Specifies the order in which account members will be returned. For more information, see [Sorting](/guides/Getting-Started/sorting).","required":false,"schema":{"type":"string","enum":["created_at","-created_at","id","-id","updated_at","-updated_at"],"x-enumDescriptions":{"created_at":"Sort in increasing order of creation","-created_at":"Sort in decreasing order of creation","id":"Sort in increasing order of ID","-id":"Sort in decreasing order of ID","updated_at":"Sort in increasing order of last update","-updated_at":"Sort in decreasing order of last update"},"example":"id"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_info`.","const":"user_authentication_info"},"name":{"type":"string","description":"Specifies the name of the user.","example":"Ron Swanson"},"given_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ron"},"family_name":{"type":["string","null"],"description":"Specifies the family name of the user.","example":"Swanson"},"middle_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ulysses"},"email":{"type":"string","description":"Specifies the email address of the user.","format":"email","example":"ron@swanson.com"}},"required":["type","name","email"],"title":"UserAuthenticationInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2025-09-08T20:29:42.282Z"},"updated_at":{"description":"The last updated date of this `user-authentication-info` object. This value also changes if subresources such as the `user-authentication-oidc-profile-info`, or `user-authentication-password-profile-info` change.The last updated date of this `user-authentication-info` object. This value also changes if subresources such as the `user-authentication-oidc-profile-info`, or `user-authentication-password-profile-info` change.","type":"string","format":"date-time","example":"2025-09-08T20:29:42.282Z"},"creation_status":{"description":"The creation status of the user authentication info.","type":"string","enum":["COMPLETE","IN_PROGRESS"],"x-enumDescriptions":{"COMPLETED":"The user authentication info has been created successfully.","IN_PROGRESS":"The creation of the user authentication info is in progress (this can happen in some edge cases, if for instance the user presses refresh while signing in for the first time). Occasionally these users may be rolled back by the system."},"example":"COMPLETE"}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123"}}}}}],"title":"UserAuthenticationInfoResponse"}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://euwest.api.elasticpath.com/v2/authentication-realms/{realmId}/user-authentication-info?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://euwest.api.elasticpath.com/v2/authentication-realms/{realmId}/user-authentication-info?page[offset]=0&page[limit]=25"},"last":{"description":"Always null if there is only one page.","type":["string","null"],"format":"uri","example":"https://euwest.api.elasticpath.com/v2/authentication-realms/{realmId}/user-authentication-info?page[offset]=0&page[limit]=25"},"next":{"description":"Always null if there is only one page.","type":["string","null"],"format":"uri","example":null},"prev":{"description":"Always null if the user is on the first page.","type":["string","null"],"format":"uri","example":null}}}}},"examples":{"list_user_authentication_info":{"summary":"List of user authentication info","value":{"data":[{"id":"40c8ecfa-0d1a-43b2-8d62-2bbbb6c4207c","type":"user_authentication_info","name":"Jane Doe","email":"jane.doe@example.com"},{"id":"ddb47241-2c69-42cd-b65f-32717cdcf9c1","type":"user_authentication_info","name":"John Smith","email":"john.smith@example.com"}],"meta":{"results":{"total":2},"page":{"limit":25,"offset":0}},"links":{"current":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info?page%5Boffset%5D=0&page%5Blimit%5D=25","first":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af/user-authentication-info?page%5Boffset%5D=0&page%5Blimit%5D=25","last":null,"next":null,"prev":null}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get an Authentication Realm

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an Authentication Realm"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms/{realmId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve a specific authentication realm by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `authentication-realm`.","const":"authentication-realm"},"name":{"type":"string","description":"Specifies the name of the authentication realm.","example":"my-auth-realm"},"duplicate_email_policy":{"type":"string","description":"The values permitted for this parameter are, `allowed` or `api_only`. In Single Sign On (SSO) each user in the Identity Provider (IdP) has a unique identifier, but different IdPs might differ in whether distinct users can share the same email address. For the `allowed` setting, when a user with a new unique identifier signs in through SSO for the first time, the system creates a new user. However, for the `api_only` setting, the system assigns the new unique identifier to the existing user in the system, in this case both the old and new unique identifier from the IdP points to the same user in Commerce. The `api_only` setting is recommended only when all configured identity providers treat e-mail address as a unique identifier for the user, otherwise a user might get access to another user’s account and data. Thus the `api_only` value can simplify administration of users.","enum":["allowed","disallowed","api_only"],"example":"allowed"},"redirect_uris":{"type":"array","description":"An array of Storefront URIs that can start Single Sign On authentication. These URIs must follow the rules for [redirection endpoints in OAuth 2.0.](https://tools.ietf.org/html/rfc6749#section-3.1.2) All URIs must start with https:// except for http://localhost.","items":{"type":"string","format":"uri"},"example":["https://example.com/callback"]},"relationships":{"type":"object","description":"Specifies the relationships for this authentication realm.","properties":{"origin":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the origin entity.","example":"0"},"type":{"type":"string","description":"The type of the origin entity.","enum":["customer-authentication-settings","merchant-realm-mappings","account_authentication_settings"]}}}}}}}},"required":["type","name"],"title":"AuthenticationRealm"},{"type":"object","properties":{"id":{"description":"The unique identifier for an Authentication Realm.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this realm.","type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23"}}}}}],"title":"AuthenticationRealmResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}},"examples":{"get_authentication_realm":{"summary":"Authentication realm","value":{"data":{"id":"45928070-44a6-448b-8246-a85aa35320af","type":"authentication-realm","name":"Buyer Organization","duplicate_email_policy":"allowed","redirect_uris":["https://example-shop.com/oidc/callback"],"relationships":{"origin":{"data":{"id":"0","type":"customer-authentication-settings"}}}},"links":{"self":"https://euwest.api.elasticpath.com/v2/authentication-realms/45928070-44a6-448b-8246-a85aa35320af"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get all Authentication Realms

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get all Authentication Realms"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/authentication-realms"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve a list of all authentication realms configured for your store.
Authentication Realms allow you to configure authentication options and manage single sign-on settings. Each realm contains users, authentication profiles, and mappings between users and authentication profiles.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[limit]","in":"query","description":"The number of records per page.","required":false,"schema":{"type":"integer","format":"int64","minimum":1,"maximum":100,"default":25}},{"name":"page[offset]","in":"query","description":"The number of records to offset the results by.","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"default":0}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `authentication-realm`.","const":"authentication-realm"},"name":{"type":"string","description":"Specifies the name of the authentication realm.","example":"my-auth-realm"},"duplicate_email_policy":{"type":"string","description":"The values permitted for this parameter are, `allowed` or `api_only`. In Single Sign On (SSO) each user in the Identity Provider (IdP) has a unique identifier, but different IdPs might differ in whether distinct users can share the same email address. For the `allowed` setting, when a user with a new unique identifier signs in through SSO for the first time, the system creates a new user. However, for the `api_only` setting, the system assigns the new unique identifier to the existing user in the system, in this case both the old and new unique identifier from the IdP points to the same user in Commerce. The `api_only` setting is recommended only when all configured identity providers treat e-mail address as a unique identifier for the user, otherwise a user might get access to another user’s account and data. Thus the `api_only` value can simplify administration of users.","enum":["allowed","disallowed","api_only"],"example":"allowed"},"redirect_uris":{"type":"array","description":"An array of Storefront URIs that can start Single Sign On authentication. These URIs must follow the rules for [redirection endpoints in OAuth 2.0.](https://tools.ietf.org/html/rfc6749#section-3.1.2) All URIs must start with https:// except for http://localhost.","items":{"type":"string","format":"uri"},"example":["https://example.com/callback"]},"relationships":{"type":"object","description":"Specifies the relationships for this authentication realm.","properties":{"origin":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the origin entity.","example":"0"},"type":{"type":"string","description":"The type of the origin entity.","enum":["customer-authentication-settings","merchant-realm-mappings","account_authentication_settings"]}}}}}}}},"required":["type","name"],"title":"AuthenticationRealm"},{"type":"object","properties":{"id":{"description":"The unique identifier for an Authentication Realm.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this realm.","type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23"}}}}}],"title":"AuthenticationRealmResponse"}},"meta":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","description":"The maximum number of records per page for this response. You can set this value up to 100.","example":25},"current":{"type":"integer","description":"The current page.","example":0},"offset":{"type":"integer","description":"The current offset by number of records, not pages. Offset is zero-based.","example":0},"total":{"type":"integer","description":"The total page count.","example":1}},"title":"MetaListPage"},"results":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of results after applying filters, if any, or all results.","example":1}},"title":"MetaListResults"}},"title":"MetaList"},"links":{"type":"object","properties":{"current":{"description":"Always the current page.","type":"string","format":"uri","example":"https://euwest.api.elasticpath.com/v2/authentication-realms/?page[offset]=0&page[limit]=25"},"first":{"description":"Always the first page.","type":"string","format":"uri","example":"https://euwest.api.elasticpath.com/v2/authentication-realms/?page[offset]=0&page[limit]=25"},"last":{"description":"Always null if there is only one page.","type":["string","null"],"format":"uri","example":"https://euwest.api.elasticpath.com/v2/authentication-realms/?page[offset]=0&page[limit]=25"},"next":{"description":"Always null if there is only one page.","type":["string","null"],"format":"uri","example":null},"prev":{"description":"Always null if the user is on the first page.","type":["string","null"],"format":"uri","example":null}}}}},"examples":{"list_authentication_realms":{"summary":"List of authentication realms","value":{"data":[{"id":"45928070-44a6-448b-8246-a85aa35320af","type":"authentication-realm","name":"Buyer Organization","duplicate_email_policy":"allowed","redirect_uris":["https://example-shop.com/oidc/callback"],"relationships":{"origin":{"data":{"id":"0","type":"customer-authentication-settings"}}}},{"id":"bbd4a3f8-6a93-44a2-8f4f-2a1e3f8b3b9c","type":"authentication-realm","name":"Merchant Organization","duplicate_email_policy":"disallowed","redirect_uris":["https://cm.example.com/oidc/callback"],"relationships":{"origin":{"data":{"id":"1","type":"merchant-realm-mappings"}}}}],"meta":{"results":{"total":2},"page":{"limit":25,"offset":0}},"links":{"current":"https://euwest.api.elasticpath.com/v2/authentication-realms/?page%5Boffset%5D=0&page%5Blimit%5D=25","first":"https://euwest.api.elasticpath.com/v2/authentication-realms/?page%5Boffset%5D=0&page%5Blimit%5D=25","last":null,"next":null,"prev":null}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unauthorized-error":{"value":{"errors":[{"title":"Unauthorized","status":"401"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## OIDC Authentication

The OIDC IDP Login endpoints handle the initiation of OpenID Connect authentication flows.

When a user needs to authenticate via OIDC, they are redirected to these endpoints which then redirect them to the configured OIDC provider for authentication.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## OIDC Profiles

An OpenID Connect Profile resource represents a specific configuration of an OpenID Connect Provider.

An authentication realm can have multiple OpenID Connect Profiles. This allows shoppers to authenticate using multiple OpenID providers. In the example shown below, Jane can login using both Apple and Google, whereas Joan can only login using Google.

![oidc profiles](/assets/oidc-profiles.png)

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Password Profiles

A `password_profile` resource represents a specific configuration that allows users to authenticate through username and password.

Password Profiles support One-Time Password Tokens, which can be used to use passwordless login or password reset.

An authentication realm can have multiple Password Profiles. You can use this flexibility in many ways. For instance, if you want to migrate an existing pool of users from another system with their own usernames and passwords, they can use one profile, while the rest of the users use another.

Another use case is enabling shopper impersonation, where shoppers can authenticate using their own username and password in one profile. Meanwhile, admins can have a different username and password for the same user in a separate profile, shown as the "Impersonation Profile". This process can be automated using a Backend-For-Frontend (BFE) or One-Time Password Tokens. In the example shown below, both John and Joan can log in with their credentials, and an admin can also log in as Joan using the "Impersonation Profile".

![password profiles](/assets/password-profiles.png)

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Create an OIDC Profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an OIDC Profile"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/authentication-realms/{realmId}/oidc-profiles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create an OpenID Connect profile for the specified authentication realm.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `oidc-profile`.","const":"oidc-profile"},"name":{"type":"string","description":"Specifies the name of the OIDC profile.","example":"my-oidc-profile"},"discovery_url":{"type":"string","description":"The OIDC discovery URL.","format":"uri","example":"https://example.com/.well-known/openid_configuration"},"client_id":{"type":"string","description":"The client ID for the OpenID Provider.","example":"my-client-id"},"client_secret":{"type":"string","description":"The client secret for the OpenID Provider.","example":"my-client-secret"}},"required":["type","name"],"title":"OidcProfile"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `oidc-profile`.","const":"oidc-profile"},"name":{"type":"string","description":"Specifies the name of the OIDC profile.","example":"my-oidc-profile"},"discovery_url":{"type":"string","description":"The OIDC discovery URL.","format":"uri","example":"https://example.com/.well-known/openid_configuration"},"client_id":{"type":"string","description":"The client ID for the OpenID Provider.","example":"my-client-id"},"client_secret":{"type":"string","description":"The client secret for the OpenID Provider.","example":"my-client-secret"}},"required":["type","name"],"title":"OidcProfile"},{"type":"object","properties":{"id":{"description":"The unique identifier for an OIDC Profile.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2025-09-08T20:58:56.355Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2025-09-08T20:58:56.355Z"},"issuer":{"description":"The OIDC issuer URL.","type":"string","format":"uri","example":"https://test.issuer.com"}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/oidc-profiles/abc123"},"authorization-endpoint":{"description":"The authorization endpoint URL.","type":"string","format":"uri"},"callback-endpoint":{"description":"The callback endpoint URL.","type":"string","format":"uri"},"client-discovery-url":{"description":"The client discovery URL.","type":"string","format":"uri"}}}}}],"title":"OidcProfileResponse"},"links":{"allOf":[{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"},{"type":"object","properties":{"authorization-endpoint":{"description":"The link that front-end applications should use to authenticate the OpenID Connect profile. The front-end application is responsible for appending all of the [required parameters](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) to the request. The endpoint also forwards some optional parameters, `display`, `prompt` and `ui_locales` to the configured Identity Provider. These parameters allow you to control the behavior of the authentication process on the Identity Provider. Additionally the query parameter `ep_report_callback_replay_error` can be set to `true` in which case if the user revisits the `callback-endpoint` multiple times (e.g., if they hit their Back button), we will redirect the user back to the front end with an [Authentication error response](https://openid.net/specs/openid-connect-core-1_0.html#AuthError) of `callback_replay`.","type":"string","format":"uri"},"callback-endpoint":{"description":"The link that should be supplied as the callback URL to the upstream authentication provider.","type":"string","format":"uri"},"client-discovery-url":{"description":"The link to the [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) document for this provider, see [here](/docs/api/single-sign-on/get-oidc-idp-stores-store-id-authentication-realms-realm-id-well-known-openid-configuration).","type":"string","format":"uri"}}}],"title":"OidcProfileLinks"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create One-Time Password Token Request

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create One-Time Password Token Request"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/authentication-realms/{realmId}/password-profiles/{profileId}/one-time-password-token-request"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a one-time password token request for the specified password profile.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","description":"The ID of the password profile.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"const":"one-time-password-token-request"},"purpose":{"type":"string","description":"An information field indicating why the user submitted this request. Your [integration](/docs/api/integrations/integrations-introduction) can inspect this field and can change subsequent processing.","enum":["reset_password","passwordless_authentication"],"x-enumDescriptions":{"reset_password":"This request is because the user does not known their password.","passwordless_authentication":"This request is because the user wants to authenticate with passwordless authentication"},"example":"password_reset"},"username":{"type":"string","description":"The username for the token request.","example":"user@example.com"}},"required":["type","purpose","username"],"title":"OneTimePasswordTokenRequestInput"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"const":"one-time-password-token-request"},"purpose":{"type":"string","description":"An information field indicating why the user submitted this request. Your [integration](/docs/api/integrations/integrations-introduction) can inspect this field and can change subsequent processing.","enum":["reset_password","passwordless_authentication"],"x-enumDescriptions":{"reset_password":"This request is because the user does not known their password.","passwordless_authentication":"This request is because the user wants to authenticate with passwordless authentication"},"example":"password_reset"},"username":{"type":"string","description":"The username for the token request.","example":"user@example.com"}},"required":["type","purpose","username"],"title":"OneTimePasswordTokenRequestInput"},{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier for the one-time password token request.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"token":{"type":"string","description":"The generated one-time password token.","example":"123456"},"expires_at":{"type":"string","format":"date-time","description":"The expiration time of the token.","example":"2023-12-01T10:30:00Z"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps"}}}],"title":"OneTimePasswordTokenRequestResponse"}}}}}},"202":{"description":"Accepted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create Password Profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Password Profile"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/authentication-realms/{realmId}/password-profiles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a password profile for the specified authentication realm.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `password_profile`.","const":"password_profile"},"name":{"type":"string","description":"Specifies the name of the password profile.","example":"my-password-profile"},"username_format":{"type":"string","description":"The format the `username` field must be in when creating or updating a [User Authentication Password Profile Info](/docs/api/single-sign-on/post-v-2-authentication-realms-realm-id-user-authentication-info-user-auth-info-id-user-authentication-password-profile-info). You can change the `username_format` setting, however, the changes apply only to the users created or updated after changing this setting. The new setting does not change the `username_format` for existing users.","enum":["email","any"],"x-enumDescriptions":{"email":"The `username` must be a valid e-mail.","any":"The `username` can be any string."},"example":"email"},"enable_one_time_password_token":{"type":"boolean","description":"This enables one time password token requests and events for authentication. This feature is disabled by default.","example":true}},"required":["type","name"],"title":"PasswordProfile"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `password_profile`.","const":"password_profile"},"name":{"type":"string","description":"Specifies the name of the password profile.","example":"my-password-profile"},"username_format":{"type":"string","description":"The format the `username` field must be in when creating or updating a [User Authentication Password Profile Info](/docs/api/single-sign-on/post-v-2-authentication-realms-realm-id-user-authentication-info-user-auth-info-id-user-authentication-password-profile-info). You can change the `username_format` setting, however, the changes apply only to the users created or updated after changing this setting. The new setting does not change the `username_format` for existing users.","enum":["email","any"],"x-enumDescriptions":{"email":"The `username` must be a valid e-mail.","any":"The `username` can be any string."},"example":"email"},"enable_one_time_password_token":{"type":"boolean","description":"This enables one time password token requests and events for authentication. This feature is disabled by default.","example":true}},"required":["type","name"],"title":"PasswordProfile"},{"type":"object","properties":{"id":{"description":"The unique identifier for a Password Profile.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this password profile.","type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/password-profiles/abc123"}}}}}],"title":"PasswordProfileResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create User Authentication OIDC Profile Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create User Authentication OIDC Profile Info"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-oidc-profile-info"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create OIDC profile information for a specific user authentication info.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_oidc_profile_info`.","const":"user_authentication_oidc_profile_info"},"oidc_profile_id":{"type":"string","description":"The ID of the associated [OIDC profile](/docs/authentication/single-sign-on/openid-connect-profiles-api/openid-connect-profiles-api-overview).","format":"uuid","example":"f1a2932f-3579-46f0-92e1-a4a80cd26e37"},"subject":{"type":"string","description":"The identifier within the issuer for the `user-authentication-info` object. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","example":"subject-123"},"issuer":{"type":"string","description":"The identifier for the issuer of the ID Token. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","format":"uri","example":"https://test.issuer.com"}},"required":["type","oidc_profile_id"],"title":"UserAuthenticationOidcProfileInfo"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_oidc_profile_info`.","const":"user_authentication_oidc_profile_info"},"oidc_profile_id":{"type":"string","description":"The ID of the associated [OIDC profile](/docs/authentication/single-sign-on/openid-connect-profiles-api/openid-connect-profiles-api-overview).","format":"uuid","example":"f1a2932f-3579-46f0-92e1-a4a80cd26e37"},"subject":{"type":"string","description":"The identifier within the issuer for the `user-authentication-info` object. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","example":"subject-123"},"issuer":{"type":"string","description":"The identifier for the issuer of the ID Token. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","format":"uri","example":"https://test.issuer.com"}},"required":["type","oidc_profile_id"],"title":"UserAuthenticationOidcProfileInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication OIDC Profile Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123/user-authentication-oidc-profile-info/def456"}}}}}],"title":"UserAuthenticationOidcProfileInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create User Authentication Password Profile Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create User Authentication Password Profile Info"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-password-profile-info"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create password profile information for a specific user authentication info.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_password_profile_info`.","const":"user_authentication_password_profile_info"},"username":{"type":"string","description":"The username used to authenticate.","example":"uauppinamepestupdate@test.com"},"password_profile_id":{"type":"string","description":"The ID of the associated password profile.","format":"uuid","example":"767e6763-014e-4b6e-8a0e-59b863ab3262"}},"required":["type","username","password_profile_id"],"title":"UserAuthenticationPasswordProfileInfo"},{"type":"object","properties":{"password":{"type":"string","description":"The password used to authenticate.","format":"password","minLength":8,"example":"P@ssw0rd123!"}},"required":["password"]}],"title":"UserAuthenticationPasswordProfileInfoInput"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_password_profile_info`.","const":"user_authentication_password_profile_info"},"username":{"type":"string","description":"The username used to authenticate.","example":"uauppinamepestupdate@test.com"},"password_profile_id":{"type":"string","description":"The ID of the associated password profile.","format":"uuid","example":"767e6763-014e-4b6e-8a0e-59b863ab3262"}},"required":["type","username","password_profile_id"],"title":"UserAuthenticationPasswordProfileInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication Password Profile Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123/user-authentication-password-profile-info/def456"}}}}}],"title":"UserAuthenticationPasswordProfileInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create User Authentication Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create User Authentication Info"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create user authentication information for the specified authentication realm.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_info`.","const":"user_authentication_info"},"name":{"type":"string","description":"Specifies the name of the user.","example":"Ron Swanson"},"given_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ron"},"family_name":{"type":["string","null"],"description":"Specifies the family name of the user.","example":"Swanson"},"middle_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ulysses"},"email":{"type":"string","description":"Specifies the email address of the user.","format":"email","example":"ron@swanson.com"}},"required":["type","name","email"],"title":"UserAuthenticationInfo"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_info`.","const":"user_authentication_info"},"name":{"type":"string","description":"Specifies the name of the user.","example":"Ron Swanson"},"given_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ron"},"family_name":{"type":["string","null"],"description":"Specifies the family name of the user.","example":"Swanson"},"middle_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ulysses"},"email":{"type":"string","description":"Specifies the email address of the user.","format":"email","example":"ron@swanson.com"}},"required":["type","name","email"],"title":"UserAuthenticationInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2025-09-08T20:29:42.282Z"},"updated_at":{"description":"The last updated date of this `user-authentication-info` object. This value also changes if subresources such as the `user-authentication-oidc-profile-info`, or `user-authentication-password-profile-info` change.The last updated date of this `user-authentication-info` object. This value also changes if subresources such as the `user-authentication-oidc-profile-info`, or `user-authentication-password-profile-info` change.","type":"string","format":"date-time","example":"2025-09-08T20:29:42.282Z"},"creation_status":{"description":"The creation status of the user authentication info.","type":"string","enum":["COMPLETE","IN_PROGRESS"],"x-enumDescriptions":{"COMPLETED":"The user authentication info has been created successfully.","IN_PROGRESS":"The creation of the user authentication info is in progress (this can happen in some edge cases, if for instance the user presses refresh while signing in for the first time). Occasionally these users may be rolled back by the system."},"example":"COMPLETE"}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123"}}}}}],"title":"UserAuthenticationInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update OIDC Profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update OIDC Profile"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/authentication-realms/{realmId}/oidc-profiles/{profileId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a specific OIDC profile by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","description":"The ID of the OIDC profile.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `oidc-profile`.","const":"oidc-profile"},"name":{"type":"string","description":"Specifies the name of the OIDC profile.","example":"my-oidc-profile"},"discovery_url":{"type":"string","description":"The OIDC discovery URL.","format":"uri","example":"https://example.com/.well-known/openid_configuration"},"client_id":{"type":"string","description":"The client ID for the OpenID Provider.","example":"my-client-id"},"client_secret":{"type":"string","description":"The client secret for the OpenID Provider.","example":"my-client-secret"}},"required":["type","name"],"title":"OidcProfile"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `oidc-profile`.","const":"oidc-profile"},"name":{"type":"string","description":"Specifies the name of the OIDC profile.","example":"my-oidc-profile"},"discovery_url":{"type":"string","description":"The OIDC discovery URL.","format":"uri","example":"https://example.com/.well-known/openid_configuration"},"client_id":{"type":"string","description":"The client ID for the OpenID Provider.","example":"my-client-id"},"client_secret":{"type":"string","description":"The client secret for the OpenID Provider.","example":"my-client-secret"}},"required":["type","name"],"title":"OidcProfile"},{"type":"object","properties":{"id":{"description":"The unique identifier for an OIDC Profile.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2025-09-08T20:58:56.355Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2025-09-08T20:58:56.355Z"},"issuer":{"description":"The OIDC issuer URL.","type":"string","format":"uri","example":"https://test.issuer.com"}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/oidc-profiles/abc123"},"authorization-endpoint":{"description":"The authorization endpoint URL.","type":"string","format":"uri"},"callback-endpoint":{"description":"The callback endpoint URL.","type":"string","format":"uri"},"client-discovery-url":{"description":"The client discovery URL.","type":"string","format":"uri"}}}}}],"title":"OidcProfileResponse"},"links":{"allOf":[{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"},{"type":"object","properties":{"authorization-endpoint":{"description":"The link that front-end applications should use to authenticate the OpenID Connect profile. The front-end application is responsible for appending all of the [required parameters](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) to the request. The endpoint also forwards some optional parameters, `display`, `prompt` and `ui_locales` to the configured Identity Provider. These parameters allow you to control the behavior of the authentication process on the Identity Provider. Additionally the query parameter `ep_report_callback_replay_error` can be set to `true` in which case if the user revisits the `callback-endpoint` multiple times (e.g., if they hit their Back button), we will redirect the user back to the front end with an [Authentication error response](https://openid.net/specs/openid-connect-core-1_0.html#AuthError) of `callback_replay`.","type":"string","format":"uri"},"callback-endpoint":{"description":"The link that should be supplied as the callback URL to the upstream authentication provider.","type":"string","format":"uri"},"client-discovery-url":{"description":"The link to the [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) document for this provider, see [here](/docs/api/single-sign-on/get-oidc-idp-stores-store-id-authentication-realms-realm-id-well-known-openid-configuration).","type":"string","format":"uri"}}}],"title":"OidcProfileLinks"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update Password Profile

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Password Profile"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/authentication-realms/{realmId}/password-profiles/{profileId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a specific password profile by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"profileId","in":"path","description":"The ID of the password profile.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `password_profile`.","const":"password_profile"},"name":{"type":"string","description":"Specifies the name of the password profile.","example":"my-password-profile"},"username_format":{"type":"string","description":"The format the `username` field must be in when creating or updating a [User Authentication Password Profile Info](/docs/api/single-sign-on/post-v-2-authentication-realms-realm-id-user-authentication-info-user-auth-info-id-user-authentication-password-profile-info). You can change the `username_format` setting, however, the changes apply only to the users created or updated after changing this setting. The new setting does not change the `username_format` for existing users.","enum":["email","any"],"x-enumDescriptions":{"email":"The `username` must be a valid e-mail.","any":"The `username` can be any string."},"example":"email"},"enable_one_time_password_token":{"type":"boolean","description":"This enables one time password token requests and events for authentication. This feature is disabled by default.","example":true}},"required":["type","name"],"title":"PasswordProfile"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `password_profile`.","const":"password_profile"},"name":{"type":"string","description":"Specifies the name of the password profile.","example":"my-password-profile"},"username_format":{"type":"string","description":"The format the `username` field must be in when creating or updating a [User Authentication Password Profile Info](/docs/api/single-sign-on/post-v-2-authentication-realms-realm-id-user-authentication-info-user-auth-info-id-user-authentication-password-profile-info). You can change the `username_format` setting, however, the changes apply only to the users created or updated after changing this setting. The new setting does not change the `username_format` for existing users.","enum":["email","any"],"x-enumDescriptions":{"email":"The `username` must be a valid e-mail.","any":"The `username` can be any string."},"example":"email"},"enable_one_time_password_token":{"type":"boolean","description":"This enables one time password token requests and events for authentication. This feature is disabled by default.","example":true}},"required":["type","name"],"title":"PasswordProfile"},{"type":"object","properties":{"id":{"description":"The unique identifier for a Password Profile.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this password profile.","type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/password-profiles/abc123"}}}}}],"title":"PasswordProfileResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update User Authentication OIDC Profile Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update User Authentication OIDC Profile Info"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-oidc-profile-info/{oidcInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update specific OIDC profile information by ID for a user.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"oidcInfoId","in":"path","description":"The ID of the OIDC profile info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_oidc_profile_info`.","const":"user_authentication_oidc_profile_info"},"oidc_profile_id":{"type":"string","description":"The ID of the associated [OIDC profile](/docs/authentication/single-sign-on/openid-connect-profiles-api/openid-connect-profiles-api-overview).","format":"uuid","example":"f1a2932f-3579-46f0-92e1-a4a80cd26e37"},"subject":{"type":"string","description":"The identifier within the issuer for the `user-authentication-info` object. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","example":"subject-123"},"issuer":{"type":"string","description":"The identifier for the issuer of the ID Token. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","format":"uri","example":"https://test.issuer.com"}},"required":["type","oidc_profile_id"],"title":"UserAuthenticationOidcProfileInfo"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_oidc_profile_info`.","const":"user_authentication_oidc_profile_info"},"oidc_profile_id":{"type":"string","description":"The ID of the associated [OIDC profile](/docs/authentication/single-sign-on/openid-connect-profiles-api/openid-connect-profiles-api-overview).","format":"uuid","example":"f1a2932f-3579-46f0-92e1-a4a80cd26e37"},"subject":{"type":"string","description":"The identifier within the issuer for the `user-authentication-info` object. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","example":"subject-123"},"issuer":{"type":"string","description":"The identifier for the issuer of the ID Token. For more information, see the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) section.","format":"uri","example":"https://test.issuer.com"}},"required":["type","oidc_profile_id"],"title":"UserAuthenticationOidcProfileInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication OIDC Profile Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123/user-authentication-oidc-profile-info/def456"}}}}}],"title":"UserAuthenticationOidcProfileInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update User Authentication Password Profile Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update User Authentication Password Profile Info"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}/user-authentication-password-profile-info/{passwordProfileInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update specific password profile information by ID for a user.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"passwordProfileInfoId","in":"path","description":"The ID of the password profile info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_password_profile_info`.","const":"user_authentication_password_profile_info"},"username":{"type":"string","description":"The username used to authenticate.","example":"uauppinamepestupdate@test.com"},"password_profile_id":{"type":"string","description":"The ID of the associated password profile.","format":"uuid","example":"767e6763-014e-4b6e-8a0e-59b863ab3262"}},"required":["type","username","password_profile_id"],"title":"UserAuthenticationPasswordProfileInfo"},{"type":"object","properties":{"password":{"type":"string","description":"The password used to authenticate.","format":"password","minLength":8,"example":"P@ssw0rd123!"}},"required":["password"]}],"title":"UserAuthenticationPasswordProfileInfoInput"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_password_profile_info`.","const":"user_authentication_password_profile_info"},"username":{"type":"string","description":"The username used to authenticate.","example":"uauppinamepestupdate@test.com"},"password_profile_id":{"type":"string","description":"The ID of the associated password profile.","format":"uuid","example":"767e6763-014e-4b6e-8a0e-59b863ab3262"}},"required":["type","username","password_profile_id"],"title":"UserAuthenticationPasswordProfileInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication Password Profile Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps","description":"Additional information for this resource."},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123/user-authentication-password-profile-info/def456"}}}}}],"title":"UserAuthenticationPasswordProfileInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update User Authentication Info

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update User Authentication Info"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/authentication-realms/{realmId}/user-authentication-info/{userAuthInfoId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update specific user authentication information by ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"userAuthInfoId","in":"path","description":"The ID of the user authentication info.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_info`.","const":"user_authentication_info"},"name":{"type":"string","description":"Specifies the name of the user.","example":"Ron Swanson"},"given_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ron"},"family_name":{"type":["string","null"],"description":"Specifies the family name of the user.","example":"Swanson"},"middle_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ulysses"},"email":{"type":"string","description":"Specifies the email address of the user.","format":"email","example":"ron@swanson.com"}},"required":["type","name","email"],"title":"UserAuthenticationInfo"}},"required":["data"]}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `user_authentication_info`.","const":"user_authentication_info"},"name":{"type":"string","description":"Specifies the name of the user.","example":"Ron Swanson"},"given_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ron"},"family_name":{"type":["string","null"],"description":"Specifies the family name of the user.","example":"Swanson"},"middle_name":{"type":["string","null"],"description":"Specifies the given name of the user.","example":"Ulysses"},"email":{"type":"string","description":"Specifies the email address of the user.","format":"email","example":"ron@swanson.com"}},"required":["type","name","email"],"title":"UserAuthenticationInfo"},{"type":"object","properties":{"id":{"description":"The unique identifier for User Authentication Info.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2025-09-08T20:29:42.282Z"},"updated_at":{"description":"The last updated date of this `user-authentication-info` object. This value also changes if subresources such as the `user-authentication-oidc-profile-info`, or `user-authentication-password-profile-info` change.The last updated date of this `user-authentication-info` object. This value also changes if subresources such as the `user-authentication-oidc-profile-info`, or `user-authentication-password-profile-info` change.","type":"string","format":"date-time","example":"2025-09-08T20:29:42.282Z"},"creation_status":{"description":"The creation status of the user authentication info.","type":"string","enum":["COMPLETE","IN_PROGRESS"],"x-enumDescriptions":{"COMPLETED":"The user authentication info has been created successfully.","IN_PROGRESS":"The creation of the user authentication info is in progress (this can happen in some edge cases, if for instance the user presses refresh while signing in for the first time). Occasionally these users may be rolled back by the system."},"example":"COMPLETE"}}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23/user-authentication-info/abc123"}}}}}],"title":"UserAuthenticationInfoResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an Authentication Realm

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Authentication Realm"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/authentication-realms/{realmId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a specific authentication realm by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"realmId","in":"path","description":"The ID of the authentication realm to update.","required":true,"schema":{"type":"string","format":"uuid"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `authentication-realm`.","const":"authentication-realm"},"name":{"type":"string","description":"Specifies the name of the authentication realm.","example":"my-auth-realm"},"duplicate_email_policy":{"type":"string","description":"The values permitted for this parameter are, `allowed` or `api_only`. In Single Sign On (SSO) each user in the Identity Provider (IdP) has a unique identifier, but different IdPs might differ in whether distinct users can share the same email address. For the `allowed` setting, when a user with a new unique identifier signs in through SSO for the first time, the system creates a new user. However, for the `api_only` setting, the system assigns the new unique identifier to the existing user in the system, in this case both the old and new unique identifier from the IdP points to the same user in Commerce. The `api_only` setting is recommended only when all configured identity providers treat e-mail address as a unique identifier for the user, otherwise a user might get access to another user’s account and data. Thus the `api_only` value can simplify administration of users.","enum":["allowed","disallowed","api_only"],"example":"allowed"},"redirect_uris":{"type":"array","description":"An array of Storefront URIs that can start Single Sign On authentication. These URIs must follow the rules for [redirection endpoints in OAuth 2.0.](https://tools.ietf.org/html/rfc6749#section-3.1.2) All URIs must start with https:// except for http://localhost.","items":{"type":"string","format":"uri"},"example":["https://example.com/callback"]},"relationships":{"type":"object","description":"Specifies the relationships for this authentication realm.","properties":{"origin":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the origin entity.","example":"0"},"type":{"type":"string","description":"The type of the origin entity.","enum":["customer-authentication-settings","merchant-realm-mappings","account_authentication_settings"]}}}}}}}},"required":["type","name"],"title":"AuthenticationRealm"}},"required":["data"]},"examples":{"Update an authentication realm":{"value":{"data":{"type":"authentication-realm","name":"updated-auth-realm","duplicate_email_policy":"disallowed","redirect_uris":["https://updated-example.com/callback"]}}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of object. Set this value to `authentication-realm`.","const":"authentication-realm"},"name":{"type":"string","description":"Specifies the name of the authentication realm.","example":"my-auth-realm"},"duplicate_email_policy":{"type":"string","description":"The values permitted for this parameter are, `allowed` or `api_only`. In Single Sign On (SSO) each user in the Identity Provider (IdP) has a unique identifier, but different IdPs might differ in whether distinct users can share the same email address. For the `allowed` setting, when a user with a new unique identifier signs in through SSO for the first time, the system creates a new user. However, for the `api_only` setting, the system assigns the new unique identifier to the existing user in the system, in this case both the old and new unique identifier from the IdP points to the same user in Commerce. The `api_only` setting is recommended only when all configured identity providers treat e-mail address as a unique identifier for the user, otherwise a user might get access to another user’s account and data. Thus the `api_only` value can simplify administration of users.","enum":["allowed","disallowed","api_only"],"example":"allowed"},"redirect_uris":{"type":"array","description":"An array of Storefront URIs that can start Single Sign On authentication. These URIs must follow the rules for [redirection endpoints in OAuth 2.0.](https://tools.ietf.org/html/rfc6749#section-3.1.2) All URIs must start with https:// except for http://localhost.","items":{"type":"string","format":"uri"},"example":["https://example.com/callback"]},"relationships":{"type":"object","description":"Specifies the relationships for this authentication realm.","properties":{"origin":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the origin entity.","example":"0"},"type":{"type":"string","description":"The type of the origin entity.","enum":["customer-authentication-settings","merchant-realm-mappings","account_authentication_settings"]}}}}}}}},"required":["type","name"],"title":"AuthenticationRealm"},{"type":"object","properties":{"id":{"description":"The unique identifier for an Authentication Realm.","type":"string","format":"uuid","example":"deb6b25f-8451-4211-9a22-95610333df23","title":"UUID"},"meta":{"description":"Additional information for this realm.","type":"object","properties":{"created_at":{"description":"The date the resource is created.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"},"updated_at":{"description":"The date the resource is updated.","type":"string","format":"date-time","example":"2021-02-23T09:40:33.882Z"}},"title":"MetaTimestamps"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri","example":"https://useast.api.elasticpath.com/v2/authentication-realms/deb6b25f-8451-4211-9a22-95610333df23"}}}}}],"title":"AuthenticationRealmResponse"},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"bad-request-error":{"value":{"errors":[{"title":"Bad Request","status":"400","detail":"Validation failed: field 'Name' on the 'min' tag."}]}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"not-found-error":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"Resource not found"}]}}}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"unprocessable-entity-error":{"value":{"errors":[{"title":"Unprocessable Entity","status":"422","detail":"Constraint violation"}]}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["status","title"],"properties":{"title":{"type":"string","description":"A brief summary of the error.","examples":["Bad Request"]},"status":{"type":"string","format":"string","description":"The HTTP response code of the error.","examples":["400"]},"detail":{"type":"string","description":"Optional additional detail about the error.","examples":["The field 'name' is required"]}},"title":"Error"}},"links":{"type":"object","properties":{"self":{"description":"A URL to the specific resource.","type":"string","format":"uri"}},"title":"SelfLink"}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"summary":"Internal server error","value":{"errors":[{"title":"Internal Server Error","status":"500","detail":"there was a problem processing your request"}]}}}}}}}}
>
  
</StatusCodes>

---

## Single Sign On API

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/single-sign-on/OpenAPISpec.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Single Sign On API"}
>
</Heading>

Single sign-on allows authentication with Commerce using an external authentication provider. Using an existing authentication provider allows for integration with company-specific or customizable authentication systems. In some cases, it can also simplify the log-in experience because they don’t need to remember another password.

Commerce supports two types of single sign-on users:

- End users, that is, customers of your store.
- Administrators, who can use single sign-on to log on to Commerce Manager.

When users need to authenticate, they are redirected to the single sign-on provider, which then communicates the result of the authentication process back to Commerce.

You can set up Commerce to allow single sign-on for end users, using the *OpenID Connect* standard.

:::note
When users authenticate using an external authentication provider, authentication details, such as username and password, are neither stored on nor sent through Commerce.
:::

## Authentication Providers and Composable Commerce

Commerce supports many OpenID Connect compatible authentication providers. For more information, see [Requirements for Authentication Providers](/guides/How-To/Authentication/get-single-sign-on-account-management-token#requirements-for-authentication-providers).

## External Reference

- [What is OpenID?](https://openid.net/foundation/)
- [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html)

## Related Resources

- [Security](/docs/authentication/security)

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"BearerToken"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
              
                Bearer format:
              
                JWT
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

  
    Contact
  
    Elastic Path: [support@elasticpath.com](mailto:support@elasticpath.com)
  
    URL: [https://www.elasticpath.com](https://www.elasticpath.com)
  

  
    License
  
    MIT

---

## User Authentication Infos

A `user-authentication-info` represents a user. This object contains information, such as the name and email address, and has sub-resources for each mechanism that the user can use to log in./single-sign-on/authentication-realm-api/authentication-realm-api-overview) and the user is configured to authenticate through that profile, then the `user-authentication-info` object is associated with a [User Authentication OpenID Connect Profile Info](/docs/api/single-sign-on/user-authentication-oidc-profile-infos) subresource.

[Account Members](/docs/api/accounts/get-v-2-account-members-account-member-id) reference User Authentication Infos directly (i.e., for every account member there is an user authentication info with the same id) and the User Authentication Info API is how you manage and configure the authentication options for that user.

[Customers (that login via OIDC)](/docs/customer-management/customer-management-api/get-a-customer) also use the User Authentication Info.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## User Authentication OIDC Profile Infos

The `user-authentication-oidc-profile-info` object is the information object about the relationship between a [User Authentication Info](/docs/api/single-sign-on/user-authentication-infos) and an [OpenID Connect Profile](/docs/api/single-sign-on/oidc-profiles).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## User Authentication Password Profile Infos

The `user-authentication-password-profile-info` object is the information object about the relationship between a [User Authentication Info](/docs/api/single-sign-on/user-authentication-infos) and a [Password Profile](/docs/api/single-sign-on/password-profiles) object.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Adds an offering's pricing options to the plan

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Adds an offering's pricing options to the plan"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}/relationships/pricing_options"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use the unique identifier of the pricing in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"plan_uuid","in":"path","description":"The unique identifier of the plan.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"description":"Enumerates a list of resources that are related.","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}}},"title":"RelationshipsRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The pricing options are added to the plan","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Attach a feature

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Attach a feature"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/features/attach"}
  context={"endpoint"}
>
  
</MethodEndpoint>

After saving an offering, you can attach new features to it at any time.

Adding new features does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"description":"A list of feature IDs to attach to the offering. See [**List Features**](/docs/api/subscriptions/list-features).","required":["features"],"properties":{"features":{"type":"array","minItems":1,"items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}},"title":"OfferingFeatureAttach"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The subscription feature is attached with the offering.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"OfferingFeature"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Build an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Build an offering"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/offerings/build"}
  context={"endpoint"}
>
  
</MethodEndpoint>

An offering includes plans and pricing options; plans are combined with one or more pricing options to form an offering. An offering can include either:

- subscription plans (created within an offering).
- Product Experience Manager products. See [**create a product**](/docs/api/pxm/products/create-product).

When you are building an offering:

- you can create new pricing options and plans.
- you can modify an existing plan and pricing options. For example, you can modify the plan price or any attributes of a pricing option included in the offering.

Here's how you build an offering:

1. Specify the plan to build with the offering. A plan can be:

     - subscription plans. Specify the subscription plan attributes. 
     - Product Experience Manager products. Specify the Product Experience Manager product ID in `external_ref` in `PlanAttributes`. For the remaining plan attributes, you can specify their values to match the values of the existing Product Experience Manager product attributes. However, you can also specify different values, depending on your requirements.

2. Specify the pricing options to build with the offering. Pricing options are the rules that govern your subscription, for example, any discount. You can combine and reuse pricing options for as many plans as you want, making it quick and easy to create your subscription offerings.
  An offering must have at least one pricing option. 

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["name","plans","pricing_options"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"proration_policy_id":{"type":"string","description":"The unique ID or external ref of the proration policy","example":"11111111-2222-3333-4444-555555555555"},"configured_features":{"type":"object","description":"Map of feature configurations keyed by plan UUID or external_ref","additionalProperties":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"},"title":"OfferingBuildPlanFeatures"},"title":"OfferingBuildConfiguredFeatures"},"pricing_option_associations":{"type":"object","description":"A map of plans keyed by plan UUID or external_ref to a list of associated pricing options, similarly keyed.","additionalProperties":{"type":"array","items":{"type":"string","description":"The unique ID or external ref of the pricing option","example":"11111111-2222-3333-4444-555555555555"},"title":"OfferingBuildPlanPricingOptions"},"title":"OfferingBuildPricingOptionAssociations"},"features":{"type":"array","description":"Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering","minItems":1,"items":{"anyOf":[{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"},{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}]}},"plans":{"type":"array","description":"Plan information to be created within the offering","minItems":1,"items":{"anyOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanExtraAttributes"}],"title":"OfferingPlanAttributes"}]}},"pricing_options":{"type":"array","description":"Pricing options information to be created within the offering","minItems":1,"items":{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"}}},"title":"BuildOffering"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The new subscription offering is created with the specified subscription plans and pricing options attached to the offering.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a dunning rule

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a dunning rule"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/dunning-rules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Dunning rules must use a `fixed` strategy. This means payments are retried on a fixed schedule. 

When an invoice is created, it immediately becomes eligible for payment by the next payment run. If the first payment attempt fails then the invoice enters dunning. In subsequent payment runs, invoices are only  considered for payment if they meet the dunning rules you create.

You can configure a dunning rule to be the default for your store. There can only be one default rule per store. All invoices in your store will then perform dunning according to the specified rules. 

:::note
If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments.
:::

The following attributes are used to define a `fixed` schedule:

- `payment_retry_unit - the unit of time used to measure the intervals between payment attempts or retries. 
- `payment_retry_interval` - the number of `payment_interval-units` to wait between each payment retry attempt.
- `payment_retries_limit` - the number of times subscriptions attempts payments retries before an `action` is taken.
- `action` - the action to take if payment is not successful.

For example, if:

- the `payment_retry_unit` is `days` 
- the `payment_retry_interval` is `2`
- the `payment_rety_limit` is `10`
- the `action` is `close`.

Subscriptions attempts to retry the payment every 2 days until 10 payment attempts have been tried. At that point, the subscription ends and it's status changes to `inacive`. 

Following on from this, you can specify that the dunning rule is no longer the default. You do not have to specify another rule to replace it. If you do remove the default dunning rule, the store defaults to the behavior that is followed when dunning is not enabled.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_dunning_rule","enum":["subscription_dunning_rule"],"title":"SubscriptionDunningRuleType"},"attributes":{"description":"The dunning rule attributes you can use to configure your payment retry strategy.\n","example":{"payment_retry_type":"fixed","payment_retry_unit":"day","payment_retry_interval":1,"payment_retries_limit":10,"action":"none"},"required":["payment_retry_type","payment_retries_limit","action"],"properties":{"payment_retry_type":{"type":"string","enum":["fixed","backoff","tiered"],"example":"fixed","description":"The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.\n","x-go-type":"model.PaymentRetryType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_interval":{"type":"integer","format":"int64","minimum":1,"maximum":1024,"example":1,"description":"The number of `payment_interval_unit`s to wait between each payment retry attempt."},"payment_retry_unit":{"type":"string","enum":["day","week"],"example":"day","description":"The unit of time used to measure the intervals between payment attempts or retries.","x-go-type":"model.PaymentRetryUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_multiplier":{"type":"number","format":"double","minimum":1,"maximum":1024,"example":1,"description":"The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types."},"payment_retries_limit":{"type":"integer","format":"int64","minimum":0,"example":5,"description":"The number of times Subscriptions attempts payment retries before `action` is taken."},"action":{"type":"string","enum":["none","pause","close","suspend"],"example":"none","description":"The action to take after all payment attempts for an invoice have failed.\n\n- None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.\n- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.\n- close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.\n","x-go-type":"model.DunningAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"default":{"type":"boolean","example":false,"description":"Set to `true` if you want this rule to be the default for the store."}},"title":"DunningRuleAttributes"}},"title":"DunningRuleCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The dunning rule set is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_dunning_rule","enum":["subscription_dunning_rule"],"title":"SubscriptionDunningRuleType"},"attributes":{"description":"The dunning rule attributes you can use to configure your payment retry strategy.\n","example":{"payment_retry_type":"fixed","payment_retry_unit":"day","payment_retry_interval":1,"payment_retries_limit":10,"action":"none"},"required":["payment_retry_type","payment_retries_limit","action"],"properties":{"payment_retry_type":{"type":"string","enum":["fixed","backoff","tiered"],"example":"fixed","description":"The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.\n","x-go-type":"model.PaymentRetryType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_interval":{"type":"integer","format":"int64","minimum":1,"maximum":1024,"example":1,"description":"The number of `payment_interval_unit`s to wait between each payment retry attempt."},"payment_retry_unit":{"type":"string","enum":["day","week"],"example":"day","description":"The unit of time used to measure the intervals between payment attempts or retries.","x-go-type":"model.PaymentRetryUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_multiplier":{"type":"number","format":"double","minimum":1,"maximum":1024,"example":1,"description":"The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types."},"payment_retries_limit":{"type":"integer","format":"int64","minimum":0,"example":5,"description":"The number of times Subscriptions attempts payment retries before `action` is taken."},"action":{"type":"string","enum":["none","pause","close","suspend"],"example":"none","description":"The action to take after all payment attempts for an invoice have failed.\n\n- None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.\n- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.\n- close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.\n","x-go-type":"model.DunningAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"default":{"type":"boolean","example":false,"description":"Set to `true` if you want this rule to be the default for the store."}},"title":"DunningRuleAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"DunningRuleMeta"}},"title":"DunningRule"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a feature

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a feature"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/features"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a feature

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_feature","enum":["subscription_feature"],"title":"SubscriptionFeatureType"},"attributes":{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}},"title":"FeatureCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The feature is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_feature","enum":["subscription_feature"],"title":"SubscriptionFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"Feature"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Import a dataset(Subscriptions)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Import a dataset"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/imports"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Import a dataset

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"multipart/form-data":{"schema":{"type":"object","required":["import_file"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"import_file":{"description":"The JSONL file you want to upload.","type":"string","format":"binary"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The import was started.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","meta","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_import","enum":["subscription_import"],"title":"SubscriptionImportType"},"attributes":{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.\n- **pending** - Commerce has received the request but is currently busy processing other requests.\n- **started** - Commerce has started processing the job.\n- **success** - The job has successfully completed.\n- **failed** - The job has failed.\n","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}}},"title":"ImportAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps","records"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"records":{"type":"object","description":"You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported into Subscriptions. However, this does not mean they are valid subscription objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added to Subscriptions.","required":["uploaded","imported"],"properties":{"uploaded":{"type":"object","properties":{"subscription_feature":{"description":"The total number of features uploaded.","type":"integer","example":50000},"subscription_subscriber":{"description":"The total number of subscribers uploaded.","type":"integer","example":50000},"subscription_offering":{"description":"The total number of offerings uploaded.","type":"integer","example":50000},"subscription":{"description":"The total number of subscriptions uploaded.","type":"integer","example":50000}},"required":["subscription_feature","subscription_subscriber","subscription_offering","subscription"]},"imported":{"properties":{"subscription_feature":{"description":"The total number of features uploaded.","type":"integer","example":50000},"subscription_subscriber":{"description":"The total number of subscribers imported.","type":"integer","example":45090},"subscription_offering":{"description":"The total number of offerings imported.","type":"integer","example":45090},"subscription":{"description":"The total number of subscriptions imported.","type":"integer","example":45090}},"required":["subscription_feature","subscription_subscriber","subscription_offering","subscription"]}},"title":"ImportRecords"}},"title":"ImportMeta"}},"title":"Import"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a refund for an invoice payment

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a refund for an invoice payment"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}/refunds"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a refund for a paid invoice.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"payment_uuid","in":"path","description":"The unique identifier of the payment.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment_refund`.","example":"subscription_invoice_payment_refund","enum":["subscription_invoice_payment_refund"],"title":"SubscriptionInvoicePaymentRefundType"},"attributes":{"type":"object","required":["amount","reason"],"properties":{"amount":{"type":"integer","format":"int64","minimum":1,"description":"The value as a whole number of the currency's smallest subdivision.","example":100},"reason":{"type":"string","minLength":1,"maxLength":1024,"description":"The reason or note for the refund","example":"Customer requested cancellation"}}}},"title":"CreateInvoicePaymentRefund"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The payment refund is completed.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes","relationships"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment_refund`.","example":"subscription_invoice_payment_refund","enum":["subscription_invoice_payment_refund"],"title":"SubscriptionInvoicePaymentRefundType"},"attributes":{"required":["amount","reason","gateway","external_refund_id","created_at"],"properties":{"amount":{"type":"integer","format":"int64","minimum":1,"description":"The value as a whole number of the currency's smallest subdivision.","example":100},"reason":{"type":"string","maxLength":1024,"description":"The reason or note for the refund","example":"Customer requested cancellation"},"gateway":{"type":"string","maxLength":1024,"example":"elastic_path_payments_stripe","description":"Specifies the payment gateway."},"external_refund_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionInvoicePaymentRefundAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"}},"title":"SubscriptionInvoicePaymentRefund"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"422":{"description":"Unprocessable Content.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"cannot-process-refund":{"value":{"errors":[{"title":"Unprocessable Content","status":"422","detail":"Unprocessable Content: cannot process the refund"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a job"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a job

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","title":"JobCreateJSON","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_job","enum":["subscription_job"],"title":"SubscriptionJobType"},"attributes":{"required":["job_type"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `tax-run` - a tax run job.\n - `payment-run` - a payment run job.\n - `import` - an import job.\n - `notification-run` - a notification run job.\n - `subscription-update` - a subscription update run job.\n","enum":["billing-run","tax-run","payment-run","import","notification-run","subscription-update"],"example":"billing-run","x-go-type":"string"}},"oneOf":[{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"billing-run"}},"title":"BillingRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"tax-run"},"taxes":{"type":"array","minItems":1,"items":{"required":["invoice_id","tax_items"],"properties":{"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}}},"title":"InvoiceTaxItems"}}},"title":"TaxRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"payment-run"}},"title":"PaymentRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"import"}},"title":"ImportJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"notification-run"}},"title":"NotificationRunJobAttributes"},{"required":["job_type","price_changes"],"properties":{"job_type":{"type":"string","example":"subscription-update"},"offering_id":{"description":"The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555"},"excluded_subscription_ids":{"description":"Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"subscription_ids":{"description":"Specific subscriptions to update. Mutually exclusive with `offering_id`.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"}},"title":"SubscriptionUpdateRunJobAttributes"}],"discriminator":{"propertyName":"job_type","mapping":{"billing-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"billing-run"}},"title":"BillingRunJobAttributes"},"tax-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"tax-run"},"taxes":{"type":"array","minItems":1,"items":{"required":["invoice_id","tax_items"],"properties":{"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}}},"title":"InvoiceTaxItems"}}},"title":"TaxRunJobAttributes"},"payment-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"payment-run"}},"title":"PaymentRunJobAttributes"},"import":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"import"}},"title":"ImportJobAttributes"},"notification-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"notification-run"}},"title":"NotificationRunJobAttributes"},"subscription-update":{"required":["job_type","price_changes"],"properties":{"job_type":{"type":"string","example":"subscription-update"},"offering_id":{"description":"The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555"},"excluded_subscription_ids":{"description":"Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"subscription_ids":{"description":"Specific subscriptions to update. Mutually exclusive with `offering_id`.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"}},"title":"SubscriptionUpdateRunJobAttributes"}}},"title":"JobCreateAttributes"}},"title":"JobCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The job was created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_job","enum":["subscription_job"],"title":"SubscriptionJobType"},"attributes":{"allOf":[{"required":["job_type"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `tax-run` - a tax run job.\n - `payment-run` - a payment run job.\n - `import` - an import job.\n - `notification-run` - a notification run job.\n - `subscription-update` - a subscription update run job.\n","enum":["billing-run","tax-run","payment-run","import","notification-run","subscription-update"],"example":"billing-run","x-go-type":"string"}},"oneOf":[{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"billing-run"}},"title":"BillingRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"tax-run"},"taxes":{"type":"array","minItems":1,"items":{"required":["invoice_id","tax_items"],"properties":{"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}}},"title":"InvoiceTaxItems"}}},"title":"TaxRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"payment-run"}},"title":"PaymentRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"import"}},"title":"ImportJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"notification-run"}},"title":"NotificationRunJobAttributes"},{"required":["job_type","price_changes"],"properties":{"job_type":{"type":"string","example":"subscription-update"},"offering_id":{"description":"The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555"},"excluded_subscription_ids":{"description":"Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"subscription_ids":{"description":"Specific subscriptions to update. Mutually exclusive with `offering_id`.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"}},"title":"SubscriptionUpdateRunJobAttributes"}],"discriminator":{"propertyName":"job_type","mapping":{"billing-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"billing-run"}},"title":"BillingRunJobAttributes"},"tax-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"tax-run"},"taxes":{"type":"array","minItems":1,"items":{"required":["invoice_id","tax_items"],"properties":{"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}}},"title":"InvoiceTaxItems"}}},"title":"TaxRunJobAttributes"},"payment-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"payment-run"}},"title":"PaymentRunJobAttributes"},"import":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"import"}},"title":"ImportJobAttributes"},"notification-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"notification-run"}},"title":"NotificationRunJobAttributes"},"subscription-update":{"required":["job_type","price_changes"],"properties":{"job_type":{"type":"string","example":"subscription-update"},"offering_id":{"description":"The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555"},"excluded_subscription_ids":{"description":"Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"subscription_ids":{"description":"Specific subscriptions to update. Mutually exclusive with `offering_id`.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"}},"title":"SubscriptionUpdateRunJobAttributes"}}},"title":"JobCreateAttributes"},{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}}},"title":"JobAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"JobResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"report":{"description":"You can track your Subscriptions billing, tax, and payment operations using reports.","oneOf":[{"required":["invoices_ready_for_payment","invoices_tax_required","invoice_failures","total_ready_for_payment","total_tax_required"],"properties":{"invoices_ready_for_payment":{"description":"The total number of invoices created that are ready for payment.","type":"integer","example":100},"invoices_tax_required":{"description":"The total number of invoices created that need taxes to be applied before payment can be made.","type":"integer","example":100},"invoice_failures":{"description":"The total number of invoices that were scheduled but creation failed.","type":"integer","example":0},"total_ready_for_payment":{"allOf":[{"description":"The total amount ready for payment invoiced in the billing run, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]},"total_tax_required":{"allOf":[{"description":"The total amount (excluding tax) invoiced in the billing run but still requiring taxes, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]}},"title":"BillingRunReport"},{"required":["invoices_updated","invoice_failures"],"properties":{"invoices_updated":{"description":"The total number of invoices to which tax was successfully added.","type":"integer","example":100},"invoice_failures":{"description":"The total number of invoices to which tax could not be added.","type":"integer","example":0}},"title":"TaxRunReport"},{"required":["total_payment_attempts","failed_payments","total_collected"],"properties":{"total_payment_attempts":{"description":"The total number of invoices for which payment was attempted.","type":"integer","example":100},"failed_payments":{"description":"The number of failed payment attempts.","type":"integer","example":0},"total_collected":{"allOf":[{"description":"The total amount collected by the payment run, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]}},"title":"PaymentRunReport"},{"required":["total_notifications_sent","failed_notifications"],"properties":{"total_notifications_sent":{"description":"The total number of notifications sent.","type":"integer","example":100},"failed_notifications":{"description":"The number of failed notifications.","type":"integer","example":0}},"title":"NotificationRunReport"},{"required":["subscriptions_updated","subscription_failures","total_processed"],"properties":{"subscriptions_updated":{"description":"The total number of subscriptions updated.","type":"integer","example":100},"subscription_failures":{"description":"The total number of subscriptions that failed to be updated.","type":"integer","example":0},"total_processed":{"description":"The total number of subscriptions processed.","type":"integer","example":100}},"title":"SubscriptionUpdateReport"}],"title":"JobReport"}},"title":"JobMeta"}},"title":"Job"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a feature directly inside an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a feature directly inside an offering"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/features"}
  context={"endpoint"}
>
  
</MethodEndpoint>

After saving an offering, you can add new features to it at any time.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}},"title":"OfferingFeatureCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The feature is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"OfferingFeature"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a plan inside an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a plan inside an offering"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/plans"}
  context={"endpoint"}
>
  
</MethodEndpoint>

After saving an offering, you can add new plans to it at any time.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanExtraAttributes"}],"title":"OfferingPlanAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"}},"title":"OfferingPlanCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The plan is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a pricing option inside an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a pricing option inside an offering"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/pricing-options"}
  context={"endpoint"}
>
  
</MethodEndpoint>

After saving an offering, you can add new pricing option to it at any time.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"}},"title":"OfferingPricingOptionCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The pricing option is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an offering"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/offerings"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create an offering

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},"relationships":{"properties":{"proration_policy":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","example":"subscription_proration_policy","enum":["subscription_proration_policy"],"title":"ProrationPolicyType"},"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"ProrationPolicyRelationshipAttributes"}},"title":"OfferingRelationships"}},"title":"OfferingCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The offering is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a Proration Policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a Proration Policy"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/proration-policies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

In Subscriptions, you configure proration by creating a proration policy and attaching it to an offering. Once you have [attached](/docs/api/subscriptions/update-offering) the policy, the proration policy applies to all subscriptions that use the offering.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_proration_policy","enum":["subscription_proration_policy"],"title":"ProrationPolicyType"},"attributes":{"required":["name","rounding"],"properties":{"name":{"type":"string","description":"A name for the proration policy.","example":"Main Policy","minLength":3,"maxLength":1024},"rounding":{"type":"string","description":"When rounding in proration, you must decide how to round the units of time used to calculate the charges.\n\n- round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use.\n- round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use.\n- round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down.\n","enum":["up","down","nearest"],"example":"up","x-go-type":"model.ProrationPolicyRounding","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"}},"title":"ProrationPolicyAttributes"}},"title":"ProrationPolicyCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The proration policy is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_proration_policy","enum":["subscription_proration_policy"],"title":"ProrationPolicyType"},"attributes":{"allOf":[{"required":["name","rounding"],"properties":{"name":{"type":"string","description":"A name for the proration policy.","example":"Main Policy","minLength":3,"maxLength":1024},"rounding":{"type":"string","description":"When rounding in proration, you must decide how to round the units of time used to calculate the charges.\n\n- round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use.\n- round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use.\n- round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down.\n","enum":["up","down","nearest"],"example":"up","x-go-type":"model.ProrationPolicyRounding","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"}},"title":"ProrationPolicyAttributes"}],"title":"ProrationPolicyResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"ProrationPolicyMeta"}},"title":"ProrationPolicy"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a schedule

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a schedule"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/schedules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a schedule

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_schedule","enum":["subscription_schedule"],"title":"SubscriptionScheduleType"},"attributes":{"required":["specification","location","job"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the schedule.","minLength":3,"maxLength":1024,"example":"Daily billing run."},"specification":{"type":"string","description":"A cron-style specification of when the jobs should be created. See [**Schedules**](/docs/api/subscriptions/schedules).","maxLength":1024,"example":"30 0 * * *"},"location":{"type":"string","description":"The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339).","maxLength":1024,"example":"Europe/London"},"job":{"required":["job_type"],"properties":{"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `payment-run` - a payment run job.\n - `notification-run` - a notification run job.\n","enum":["billing-run","payment-run","notification-run"],"example":"billing-run","x-go-type":"model.JobType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"ScheduleJobType"}},"title":"ScheduleJob"}},"title":"ScheduleAttributes"}},"title":"ScheduleCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The schedule is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_schedule","enum":["subscription_schedule"],"title":"SubscriptionScheduleType"},"attributes":{"allOf":[{"required":["specification","location","job"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the schedule.","minLength":3,"maxLength":1024,"example":"Daily billing run."},"specification":{"type":"string","description":"A cron-style specification of when the jobs should be created. See [**Schedules**](/docs/api/subscriptions/schedules).","maxLength":1024,"example":"30 0 * * *"},"location":{"type":"string","description":"The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339).","maxLength":1024,"example":"Europe/London"},"job":{"required":["job_type"],"properties":{"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `payment-run` - a payment run job.\n - `notification-run` - a notification run job.\n","enum":["billing-run","payment-run","notification-run"],"example":"billing-run","x-go-type":"model.JobType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"ScheduleJobType"}},"title":"ScheduleJob"}},"title":"ScheduleAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"ScheduleResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"scheduled_for":{"type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"ScheduleMeta"}},"title":"Schedule"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a subscriber

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a subscriber"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/subscribers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a subscriber

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","example":"subscription_subscriber","enum":["subscription_subscriber"],"title":"SubscriptionSubscriberType"},"attributes":{"required":["name","email","account_id"],"properties":{"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"name":{"type":"string","description":"The name of the subscriber.","minLength":3,"maxLength":1024,"example":"John Doe"},"email":{"type":"string","format":"email","description":"The email of the subscriber.","minLength":3,"maxLength":1024,"example":"john.doe@example.com","x-go-type":"types.Email","x-go-type-import":{"name":"email","path":"github.com/oapi-codegen/runtime/types"}},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriberAttributes"}},"title":"SubscriberCreate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The subscriber is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_subscriber","enum":["subscription_subscriber"],"title":"SubscriptionSubscriberType"},"attributes":{"allOf":[{"required":["name","email","account_id"],"properties":{"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"name":{"type":"string","description":"The name of the subscriber.","minLength":3,"maxLength":1024,"example":"John Doe"},"email":{"type":"string","format":"email","description":"The email of the subscriber.","minLength":3,"maxLength":1024,"example":"john.doe@example.com","x-go-type":"types.Email","x-go-type-import":{"name":"email","path":"github.com/oapi-codegen/runtime/types"}},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriberAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"SubscriberResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"feature_entitlements":{"type":"array","description":"A list of entitlement tags currently active for the subscriber","example":["tag1","tag2"],"items":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"SubscriberMeta"}},"title":"Subscriber"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a subscription state

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a subscription state"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/states"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. 

A subscription can have the following states:

- `pending` 
- `canceled`
- `paused`
- `resumed`
For more information, see [Managing the Subscription Lifecycle](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).

Immediate cancellation (`cancel` with `cancel_immediately: true`) ends the subscription and updates entitlements in this request; it does **not** issue refunds or modify paid invoices. Use payments refund flows separately if needed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["type","attributes"],"properties":{"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_state`.","example":"subscription_state","enum":["subscription_state"],"title":"SubscriptionStateType"},"attributes":{"required":["action"],"properties":{"action":{"type":"string","description":"The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n","example":"cancel","enum":["cancel","pause","resume","pending"],"x-go-type":"model.SubscriptionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"SubscriptionStateAction"},"cancel_immediately":{"type":"boolean","default":false,"example":false,"description":"When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n"}},"title":"SubscriptionStateAttributes"}},"title":"ChangeState"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The subscription's state has changed."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"422":{"description":"Unprocessable Content.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"cannot-process-refund":{"value":{"errors":[{"title":"Unprocessable Content","status":"422","detail":"Unprocessable Content: cannot process the refund"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Create a subscription

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a subscription"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v2/subscriptions/subscriptions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a subscription

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["account_id","currency","name","email","manual_payments"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"address_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"offering_external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"offering_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"pricing_option_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"currency":{"type":"string","description":"The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase.","maxLength":1024,"example":"USD","title":"CurrencyIdentifier"},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type","customer_id","card_id"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"CreatePaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type","customer_id","card_id"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"CreatePaymentAuthorityStripe"},{"type":"object","required":["type","payment_profile_id","customer_profile_id"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"CreatePaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type","customer_id","card_id"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"CreatePaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type","customer_id","card_id"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"CreatePaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type","payment_profile_id","customer_profile_id"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"CreatePaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"CreatePaymentAuthority"},"manual_payments":{"type":"boolean","example":false,"default":false,"description":"When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments).","title":"ManualPayments"},"name":{"type":"string","minLength":3,"maxLength":1024,"example":"Albert Einstein"},"email":{"type":"string","format":"email","minLength":3,"maxLength":1024,"example":"albert@elasticpath.com"},"pending":{"type":"boolean","description":"Whether a subscription is pending activation or not. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription).","example":false},"first_invoice_paid":{"type":"boolean","description":"Indicates that payment for the first billing period of the subscription has already been taken. As well as creating the subscription a settled invoice is created to cover the first period.","example":false},"started_at":{"description":"When importing an active subscription from an existing system you can specify the date and time of the start of the most recent period. This may only be supplied when `first_invoice_paid` is true. As well as creating the subscription a settled invoice is created to cover the correct billing period.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"override_first_period_end_date":{"description":"Optional. May only be set when `started_at` is set. When supplied, overrides the default first billing period end (start + 1 interval). The first billing period runs from the subscription start date to this date. The subscriber is charged the standard period price for the first period. Subsequent billing periods start from this date. Must be after the subscription start date.","type":"string","format":"date-time","example":"2027-02-01T00:00:00Z"},"offering":{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},"features":{"type":"array","description":"Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering","minItems":1,"items":{"anyOf":[{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"},{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}]}},"plans":{"type":"array","minItems":1,"items":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"properties":{"meta":{"properties":{"selected":{"type":"boolean","example":true,"description":"One item must be selected for use in the subscription"}},"title":"SelectedMetaAttributes"}},"title":"SelectedMeta"}],"title":"PlanAttributesAndSelectedMeta"}},"pricing_options":{"type":"array","minItems":1,"items":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"properties":{"meta":{"properties":{"selected":{"type":"boolean","example":true,"description":"One item must be selected for use in the subscription"}},"title":"SelectedMetaAttributes"}},"title":"SelectedMeta"}],"title":"PricingOptionAttributesAndSelectedMeta"}},"configured_features":{"type":"object","description":"Map of feature configurations keyed by plan UUID or external_ref","additionalProperties":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"},"title":"OfferingBuildPlanFeatures"},"title":"OfferingBuildConfiguredFeatures"},"pricing_option_associations":{"type":"object","description":"A map of plans keyed by plan UUID or external_ref to a list of associated pricing options, similarly keyed.","additionalProperties":{"type":"array","items":{"type":"string","description":"The unique ID or external ref of the pricing option","example":"11111111-2222-3333-4444-555555555555"},"title":"OfferingBuildPlanPricingOptions"},"title":"OfferingBuildPricingOptionAssociations"},"selected_plan":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"selected_pricing_option":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"order":{"description":"A subscription may optionally be associated with an item in an order by supplying both the order ID and the ID of the item within that order.","required":["order_id","order_item_id"],"properties":{"order_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"order_item_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"BuildSubscriptionOrder"},"meta":{"readOnly":true,"required":["owner","timestamps","status","canceled","paused","closed","pending","suspended","invoice_after","manual_payments","first_invoice_prepaid"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"canceled_at":{"description":"The date and time a subscription was cancelled.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"paused_at":{"description":"The date and time a subscription was paused.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"resumed_at":{"description":"The date and time a subscription was resumed.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"end_date":{"description":"The date and time a subscription will end.\n- If the subscription offering pricing option end behavior is `close`, `end_date` is set to the billing period end date upon subscription creation.\n- If the subscription offering pricing option end behavior is \"roll\": `end_date` is set to the billing period end date when the subscription is cancelled.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live_after":{"description":"The date and time a subscription will go live and become active.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live":{"description":"The date and time a subscription was released from the pending state and made active.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"SubscriptionTimestamps"},"status":{"type":"string","description":"The status of a subscription, either `active` or `inactive`.","example":"active","enum":["active","inactive"],"x-go-type":"model.SubscriptionStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"Status"},"state":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_state`.","example":"subscription_state","enum":["subscription_state"],"title":"SubscriptionStateType"},"attributes":{"required":["action"],"properties":{"action":{"type":"string","description":"The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n","example":"cancel","enum":["cancel","pause","resume","pending"],"x-go-type":"model.SubscriptionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"SubscriptionStateAction"},"cancel_immediately":{"type":"boolean","default":false,"example":false,"description":"When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n"}},"title":"SubscriptionStateAttributes"},"meta":{"readOnly":true,"required":["created_at"],"properties":{"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"StateMeta"}},"title":"SubscriptionState"},"manual_payments":{"type":"boolean","example":false,"default":false,"description":"When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments).","title":"ManualPayments"},"first_invoice_prepaid":{"type":"boolean","description":"Indicates that the first billing period of this subscription was paid for outside of the subscriptions service.","example":false},"canceled":{"type":"boolean","description":"Whether a subscription is canceled or not.","example":true},"paused":{"type":"boolean","description":"Whether a subscription is paused or not.","example":true},"closed":{"type":"boolean","description":"Whether a subscription is closed or not.","example":true},"suspended":{"type":"boolean","description":"Whether a subscription is suspended or not.","example":false},"pending":{"type":"boolean","description":"Whether a subscription is pending activation or not.","example":false},"invoice_after":{"description":"The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pending_price_change":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"price_update_history":{"description":"A history of price updates that have been applied to this subscription.","type":"array","x-go-type-skip-optional-pointer":true,"items":{"description":"A record of the previous prices of a subscription before a price change was applied","required":["price_changes","valid_until"],"properties":{"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"valid_until":{"description":"The date and time when the prices were changed (when these previous prices stopped being active)","type":"string","format":"date-time","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionPriceUpdateHistoryEntry"}}},"title":"SubscriptionMeta"}},"title":"BuildSubscription"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"Success. The subscription is created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription","enum":["subscription"],"title":"SubscriptionType"},"attributes":{"required":["account_id","pricing_option_id","plan_id","offering","currency","name","email"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"address_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"offering":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"},"pricing_option_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"currency":{"type":"string","description":"The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase.","maxLength":1024,"example":"USD","title":"CurrencyIdentifier"},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriptionAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","status","canceled","paused","closed","pending","suspended","invoice_after","manual_payments","first_invoice_prepaid"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"canceled_at":{"description":"The date and time a subscription was cancelled.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"paused_at":{"description":"The date and time a subscription was paused.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"resumed_at":{"description":"The date and time a subscription was resumed.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"end_date":{"description":"The date and time a subscription will end.\n- If the subscription offering pricing option end behavior is `close`, `end_date` is set to the billing period end date upon subscription creation.\n- If the subscription offering pricing option end behavior is \"roll\": `end_date` is set to the billing period end date when the subscription is cancelled.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live_after":{"description":"The date and time a subscription will go live and become active.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live":{"description":"The date and time a subscription was released from the pending state and made active.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"SubscriptionTimestamps"},"status":{"type":"string","description":"The status of a subscription, either `active` or `inactive`.","example":"active","enum":["active","inactive"],"x-go-type":"model.SubscriptionStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"Status"},"state":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_state`.","example":"subscription_state","enum":["subscription_state"],"title":"SubscriptionStateType"},"attributes":{"required":["action"],"properties":{"action":{"type":"string","description":"The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n","example":"cancel","enum":["cancel","pause","resume","pending"],"x-go-type":"model.SubscriptionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"SubscriptionStateAction"},"cancel_immediately":{"type":"boolean","default":false,"example":false,"description":"When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n"}},"title":"SubscriptionStateAttributes"},"meta":{"readOnly":true,"required":["created_at"],"properties":{"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"StateMeta"}},"title":"SubscriptionState"},"manual_payments":{"type":"boolean","example":false,"default":false,"description":"When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments).","title":"ManualPayments"},"first_invoice_prepaid":{"type":"boolean","description":"Indicates that the first billing period of this subscription was paid for outside of the subscriptions service.","example":false},"canceled":{"type":"boolean","description":"Whether a subscription is canceled or not.","example":true},"paused":{"type":"boolean","description":"Whether a subscription is paused or not.","example":true},"closed":{"type":"boolean","description":"Whether a subscription is closed or not.","example":true},"suspended":{"type":"boolean","description":"Whether a subscription is suspended or not.","example":false},"pending":{"type":"boolean","description":"Whether a subscription is pending activation or not.","example":false},"invoice_after":{"description":"The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pending_price_change":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"price_update_history":{"description":"A history of price updates that have been applied to this subscription.","type":"array","x-go-type-skip-optional-pointer":true,"items":{"description":"A record of the previous prices of a subscription before a price change was applied","required":["price_changes","valid_until"],"properties":{"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"valid_until":{"description":"The date and time when the prices were changed (when these previous prices stopped being active)","type":"string","format":"date-time","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionPriceUpdateHistoryEntry"}}},"title":"SubscriptionMeta"}},"title":"Subscription"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete dunning rules

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete dunning rules"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/dunning-rules/{dunning_rule_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can delete a dunning rule at any time. If a dunning rule is deleted then Subscriptions reverts to the configuration used if no dunning rule is set; payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments. See [Dunning Rules](/docs/api/subscriptions/dunning-rules).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"dunning_rule_uuid","in":"path","description":"The unique identifier of a dunning rule set.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The dunning rule is removed."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete feature

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete feature"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/features/{feature_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Remove a feature.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"feature_uuid","in":"path","description":"The unique identifier of a feature.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The feature is removed."},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete job"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/jobs/{job_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete job

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"job_uuid","in":"path","description":"The unique identifier of the job.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The job was deleted."},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}}}}
>
  
</StatusCodes>

---

## Remove a feature from an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Remove a feature from an offering"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/features/{feature_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

After saving an offering, you can remove features from it at any time.

 Removing a feature from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"feature_uuid","in":"path","description":"The unique identifier of the feature.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The subscription feature is removed from the offering."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}}}}
>
  
</StatusCodes>

---

## Remove a plan from an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Remove a plan from an offering"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

After saving an offering, you can remove plans from it at any time.

 Removing a plan from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"plan_uuid","in":"path","description":"The unique identifier of the plan.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The subscription plan is removed from the offering."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}}}}
>
  
</StatusCodes>

---

## Remove a pricing option from an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Remove a pricing option from an offering"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/pricing-options/{pricing_option_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

After saving an offering, you can remove pricing options from it at any time.

Removing a pricing option from an offering does not affect any existing active subscriptions. The changes take effect on all new subscriptions that are created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"pricing_option_uuid","in":"path","description":"The unique identifier of the pricing option.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The subscription pricing option is no longer associated with the offering."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete offering"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/offerings/{offering_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

When a subscription is created, it creates a snapshot of the offering. This means you can delete an offering without affecting any active subscriptions.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The subscription offering is removed."},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete proration policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete proration policy"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/proration-policies/{proration_policy_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A proration policy cannot be deleted if it is being used by any subscriptions. This means you must detach a proration policy that you want to delete from any offerings using that policy before deleting the policy. See [Remove a proration policy from an offering](/docs/api/subscriptions/update-offering).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"proration_policy_uuid","in":"path","description":"The unique identifier of a proration policy.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The proration policy details are removed."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete schedule

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete schedule"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/schedules/{schedule_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete schedule

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"schedule_uuid","in":"path","description":"The unique identifier of the schedule.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The schedule is removed."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete subscriber

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete subscriber"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/subscribers/{subscriber_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete subscriber

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscriber_uuid","in":"path","description":"The unique identifier of the subscriber.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The subscriber is removed."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Delete a subscription

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a subscription"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a subscription

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The subscription is removed."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Dunning Rules

Dunning is the process of handling failed payment attempts. This is important for recovering revenue from failed payments, reduces customer churn and maintains cashflow. By implementing efficient dunning processes, you can enhance financial health and operational efficiency.

Subscriptions enables you to create a dunning rule that allows you to configure payment retry schedules. Subscriptions retries failed payments automatically. You can customize the timing and frequency of the payment retries.

Dunning is enabled by default. You can choose to disable dunning. If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments.

- Do nothing - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.
- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.
- close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment. 

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Features

A feature indicates some benefit that is received as a result of having an active subscription. This translates to tags being applied to the subscriber's account allowing access to some resource to be controlled.

There are three types of feature - `access`, `promotion`, and `usage`.

The `access` feature is designed to simply give access to some resource, for example a streaming service. If its tag is present on the subscriber's account then access to that resource should be provided.

The `promotion` feature coupled with the [promotions service](/docs/promotions-builder/overview) allows subscribers to get access to a specific promotion. This is achieved using a tag which is used as a constraint on the promotion. A promotion feature may have multiple promotions associated with it, but just one must be selected when configuring the feature for an offering's plan.

 The `usage` feature is designed to measure some sort of usage of a resource. This currently relies on [commerce extensions](/docs/api/commerce-extensions/commerce-extensions-introduction) to manage usage.

 Once defined a feature may be attached to an offering, making it available for use with any of that offering's plans. Once attached it must be configured for each of the offering's plans it is applicable to. For the `promotion` feature this involves specifying which of that feature's tags, and hence which promotion, should be applied when subscribed to that offering. Similarly, for the `promotion` feature the default value for the usage metric must be supplied.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Get dunning rule policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get dunning rule policy"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/dunning-rules/{dunning_rule_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get dunning rule policy

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"dunning_rule_uuid","in":"path","description":"The unique identifier of a dunning rule set.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The dunning rule details are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_dunning_rule","enum":["subscription_dunning_rule"],"title":"SubscriptionDunningRuleType"},"attributes":{"description":"The dunning rule attributes you can use to configure your payment retry strategy.\n","example":{"payment_retry_type":"fixed","payment_retry_unit":"day","payment_retry_interval":1,"payment_retries_limit":10,"action":"none"},"required":["payment_retry_type","payment_retries_limit","action"],"properties":{"payment_retry_type":{"type":"string","enum":["fixed","backoff","tiered"],"example":"fixed","description":"The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.\n","x-go-type":"model.PaymentRetryType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_interval":{"type":"integer","format":"int64","minimum":1,"maximum":1024,"example":1,"description":"The number of `payment_interval_unit`s to wait between each payment retry attempt."},"payment_retry_unit":{"type":"string","enum":["day","week"],"example":"day","description":"The unit of time used to measure the intervals between payment attempts or retries.","x-go-type":"model.PaymentRetryUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_multiplier":{"type":"number","format":"double","minimum":1,"maximum":1024,"example":1,"description":"The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types."},"payment_retries_limit":{"type":"integer","format":"int64","minimum":0,"example":5,"description":"The number of times Subscriptions attempts payment retries before `action` is taken."},"action":{"type":"string","enum":["none","pause","close","suspend"],"example":"none","description":"The action to take after all payment attempts for an invoice have failed.\n\n- None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.\n- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.\n- close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.\n","x-go-type":"model.DunningAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"default":{"type":"boolean","example":false,"description":"Set to `true` if you want this rule to be the default for the store."}},"title":"DunningRuleAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"DunningRuleMeta"}},"title":"DunningRule"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get feature

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get feature"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/features/{feature_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get feature

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"feature_uuid","in":"path","description":"The unique identifier of a feature.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The feature details are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_feature","enum":["subscription_feature"],"title":"SubscriptionFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"Feature"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get import errors(Subscriptions)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get import errors"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/imports/{import_uuid}/errors"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all errors encountered as part of the import. Each error is attributed to a line in the JSONL file 
imported, so for example, if at line 1 in your JSONL you had a subscription_offering without a name, there would
be a minimum string error for the `name` attribute with `"line_number": 1`.

Errors are also ordered by line number ascending, and can be paginated.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"import_uuid","in":"path","description":"The unique identifier of the import.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The import errors are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_import_error","enum":["subscription_import_error"],"title":"SubscriptionImportErrorType"},"meta":{"type":"object","required":["owner","timestamps","error","field","line_number"],"properties":{"owner":{"type":"string","example":"store"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"error":{"type":"string","example":"offering name cannot be empty"},"field":{"type":"string","example":"name"},"line_number":{"type":"integer","description":"The line in the imported JSONL file at which the validation error occurred. Starts from 1.","example":123},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"}},"title":"SubscriptionImportErrorMeta"}},"title":"SubscriptionImportError"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get import(Subscriptions)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get import"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/imports/{import_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the import job for the specified ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"import_uuid","in":"path","description":"The unique identifier of the import.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The import is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","meta","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_import","enum":["subscription_import"],"title":"SubscriptionImportType"},"attributes":{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.\n- **pending** - Commerce has received the request but is currently busy processing other requests.\n- **started** - Commerce has started processing the job.\n- **success** - The job has successfully completed.\n- **failed** - The job has failed.\n","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}}},"title":"ImportAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps","records"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"records":{"type":"object","description":"You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported into Subscriptions. However, this does not mean they are valid subscription objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added to Subscriptions.","required":["uploaded","imported"],"properties":{"uploaded":{"type":"object","properties":{"subscription_feature":{"description":"The total number of features uploaded.","type":"integer","example":50000},"subscription_subscriber":{"description":"The total number of subscribers uploaded.","type":"integer","example":50000},"subscription_offering":{"description":"The total number of offerings uploaded.","type":"integer","example":50000},"subscription":{"description":"The total number of subscriptions uploaded.","type":"integer","example":50000}},"required":["subscription_feature","subscription_subscriber","subscription_offering","subscription"]},"imported":{"properties":{"subscription_feature":{"description":"The total number of features uploaded.","type":"integer","example":50000},"subscription_subscriber":{"description":"The total number of subscribers imported.","type":"integer","example":45090},"subscription_offering":{"description":"The total number of offerings imported.","type":"integer","example":45090},"subscription":{"description":"The total number of subscriptions imported.","type":"integer","example":45090}},"required":["subscription_feature","subscription_subscriber","subscription_offering","subscription"]}},"title":"ImportRecords"}},"title":"ImportMeta"}},"title":"Import"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a refund for an invoice payment

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a refund for an invoice payment"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}/refunds/{refund_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a refund for a paid invoice.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"payment_uuid","in":"path","description":"The unique identifier of the payment.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"refund_uuid","in":"path","description":"The unique identifier of the refund.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Specific refund for the invoice payment is returned","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes","relationships"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment_refund`.","example":"subscription_invoice_payment_refund","enum":["subscription_invoice_payment_refund"],"title":"SubscriptionInvoicePaymentRefundType"},"attributes":{"required":["amount","reason","gateway","external_refund_id","created_at"],"properties":{"amount":{"type":"integer","format":"int64","minimum":1,"description":"The value as a whole number of the currency's smallest subdivision.","example":100},"reason":{"type":"string","maxLength":1024,"description":"The reason or note for the refund","example":"Customer requested cancellation"},"gateway":{"type":"string","maxLength":1024,"example":"elastic_path_payments_stripe","description":"Specifies the payment gateway."},"external_refund_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionInvoicePaymentRefundAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"}},"title":"SubscriptionInvoicePaymentRefund"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get invoice payment

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get invoice payment"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get invoice payment

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"payment_uuid","in":"path","description":"The unique identifier of the payment.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Specific payment for the invoice is returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment`.","example":"subscription_invoice_payment","enum":["subscription_invoice_payment"],"title":"SubscriptionInvoicePaymentType"},"attributes":{"required":["success","amount","gateway"],"properties":{"success":{"type":"boolean","example":true,"description":"Whether the payment was successful."},"pending":{"type":"boolean","example":true,"description":"Whether the payment is pending (only for manual payments)."},"gateway":{"type":"string","maxLength":1024,"example":"elastic_path_payments_stripe","description":"Specifies the payment gateway."},"external_payment_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"failure_detail":{"type":"object","description":"The reason the payment failed.","properties":{"reason":{"type":"string","example":"Card Failure"}},"title":"PaymentFailureDetail"},"amount":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"}},"title":"SubscriptionInvoicePaymentAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps","invoice_id","subscription_id","job_id","manual_payment"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"job_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"payment_taken_at":{"description":"The date and time a payment was taken.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoicePaymentTimestamps"},"manual_payment":{"type":"boolean","example":false,"description":"Whether manual payments are enabled or the payment will be handled by the configured gateway."}},"title":"SubscriptionInvoicePaymentMeta"}},"title":"SubscriptionInvoicePayment"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get invoice

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get invoice"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/invoices/{invoice_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get invoice

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the invoice are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"description":"This represents the type of resource object being returned. Always `subscription_invoice`.","type":"string","example":"subscription_invoice","enum":["subscription_invoice"],"title":"SubscriptionInvoiceType"},"attributes":{"required":["billing_period","pro_forma","invoice_items","outstanding","tax_required","payment_retries_limit_reached","manual_payment_pending"],"properties":{"billing_period":{"description":"A period of time between a start and end point.","required":["start","end"],"properties":{"start":{"description":"The date and time a billing period started.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"end":{"description":"The date and time a billing period ended.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"TimePeriod"},"invoice_items":{"type":"array","items":{"required":["description","price"],"properties":{"description":{"type":"string","description":"A description of the subscribed item.","example":"Magazine issue"},"price":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"from_time_period":{"description":"The start date and time of the billing period in this price","type":"string","example":"2017-01-10T11:41:19.244842Z"},"until_time_period":{"description":"The end date and time of the billing period in this price","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionInvoiceItem"}},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}},"outstanding":{"type":"boolean","description":"The invoice still requires payment if `true`.","example":true},"number":{"type":"integer","description":"A sequential number assigned by the billing run.","example":1},"tax_required":{"type":"boolean","description":"Whether tax is required for this invoice.","example":true},"payment_retries_limit_reached":{"type":"boolean","description":"Whether the limit of payment retries has been reached.","example":false},"updated_at":{"description":"The date and time an invoice was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time an invoice was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pro_forma":{"description":"Whether the invoice is a Pro Forma invoice (generated ahead of payment) or not.\n\nPro Forma Invoices are created ahead of payment time (for example, a week in advance of payment so\nyou can notify customers) and will not be picked up by a payment run until on or after their valid_from\ndate.\n","type":"boolean","example":false},"valid_from":{"description":"The date and time at which an invoice will be valid from.\n\nIf generated with no lead time then the invoice will be valid immediately.\n\nIf generated with a lead time, then the valid_from will be the data at which the Invoice transitions from\nit's Pro Forma state to one that can have payment taken.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"manual_payment_pending":{"type":"boolean","description":"Whether there is a manual pending payment pending on the invoice.","example":true}},"title":"SubscriptionInvoiceAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","proration_events","pro_rata_remaining_value","display_price"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"subscriber_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"price":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice","description":"Invoice totals formatted for display (`with_tax`, `without_tax`, `tax`). Amounts are in the\ncurrency's smallest subdivision.\n"},"notifications":{"description":"A list of notifications scheduled for this invoice. These are derived from the notification\nschedules configured on the pricing option at the time the invoice was created. Each notification\nhas a due date calculated relative to the billing period end date.\n","type":"array","items":{"description":"A notification scheduled for an invoice.","required":["name","due"],"properties":{"name":{"description":"The name of the notification schedule that generated this notification.","type":"string","example":"7 days before renewal"},"due":{"description":"The date and time when the notification is due to be sent.","type":"string","format":"date-time","example":"2024-01-24T00:00:00Z"},"sent_at":{"description":"The date and time when the notification was sent.","type":"string","format":"date-time","example":"2024-01-24T00:00:00Z"}},"title":"InvoiceNotification"}},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"taxes_added_at":{"description":"The date and time taxes were added to an invoice.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoiceTimestamps"},"proration_events":{"type":"array","items":{"required":["proration_policy_id","billing_cost_before_proration","refunded_amount_for_unused_pricing_option","new_pricing_option_cost","prorated_at"],"properties":{"proration_policy_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"billing_cost_before_proration":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision","example":100},"refunded_amount_for_unused_pricing_option":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"new_pricing_option_cost":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"prorated_at":{"description":"The date and time the subscription was prorated.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"ProrationEvent"}},"pro_rata_remaining_value":{"type":"integer","format":"int64","description":"The pro-rated remaining value for the billing period","example":500}},"title":"SubscriptionInvoiceMeta"}},"title":"SubscriptionInvoice"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get job

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get job"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/jobs/{job_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get job

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"job_uuid","in":"path","description":"The unique identifier of the job.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The job is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_job","enum":["subscription_job"],"title":"SubscriptionJobType"},"attributes":{"allOf":[{"required":["job_type"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `tax-run` - a tax run job.\n - `payment-run` - a payment run job.\n - `import` - an import job.\n - `notification-run` - a notification run job.\n - `subscription-update` - a subscription update run job.\n","enum":["billing-run","tax-run","payment-run","import","notification-run","subscription-update"],"example":"billing-run","x-go-type":"string"}},"oneOf":[{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"billing-run"}},"title":"BillingRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"tax-run"},"taxes":{"type":"array","minItems":1,"items":{"required":["invoice_id","tax_items"],"properties":{"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}}},"title":"InvoiceTaxItems"}}},"title":"TaxRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"payment-run"}},"title":"PaymentRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"import"}},"title":"ImportJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"notification-run"}},"title":"NotificationRunJobAttributes"},{"required":["job_type","price_changes"],"properties":{"job_type":{"type":"string","example":"subscription-update"},"offering_id":{"description":"The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555"},"excluded_subscription_ids":{"description":"Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"subscription_ids":{"description":"Specific subscriptions to update. Mutually exclusive with `offering_id`.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"}},"title":"SubscriptionUpdateRunJobAttributes"}],"discriminator":{"propertyName":"job_type","mapping":{"billing-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"billing-run"}},"title":"BillingRunJobAttributes"},"tax-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"tax-run"},"taxes":{"type":"array","minItems":1,"items":{"required":["invoice_id","tax_items"],"properties":{"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}}},"title":"InvoiceTaxItems"}}},"title":"TaxRunJobAttributes"},"payment-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"payment-run"}},"title":"PaymentRunJobAttributes"},"import":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"import"}},"title":"ImportJobAttributes"},"notification-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"notification-run"}},"title":"NotificationRunJobAttributes"},"subscription-update":{"required":["job_type","price_changes"],"properties":{"job_type":{"type":"string","example":"subscription-update"},"offering_id":{"description":"The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555"},"excluded_subscription_ids":{"description":"Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"subscription_ids":{"description":"Specific subscriptions to update. Mutually exclusive with `offering_id`.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"}},"title":"SubscriptionUpdateRunJobAttributes"}}},"title":"JobCreateAttributes"},{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}}},"title":"JobAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"JobResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"report":{"description":"You can track your Subscriptions billing, tax, and payment operations using reports.","oneOf":[{"required":["invoices_ready_for_payment","invoices_tax_required","invoice_failures","total_ready_for_payment","total_tax_required"],"properties":{"invoices_ready_for_payment":{"description":"The total number of invoices created that are ready for payment.","type":"integer","example":100},"invoices_tax_required":{"description":"The total number of invoices created that need taxes to be applied before payment can be made.","type":"integer","example":100},"invoice_failures":{"description":"The total number of invoices that were scheduled but creation failed.","type":"integer","example":0},"total_ready_for_payment":{"allOf":[{"description":"The total amount ready for payment invoiced in the billing run, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]},"total_tax_required":{"allOf":[{"description":"The total amount (excluding tax) invoiced in the billing run but still requiring taxes, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]}},"title":"BillingRunReport"},{"required":["invoices_updated","invoice_failures"],"properties":{"invoices_updated":{"description":"The total number of invoices to which tax was successfully added.","type":"integer","example":100},"invoice_failures":{"description":"The total number of invoices to which tax could not be added.","type":"integer","example":0}},"title":"TaxRunReport"},{"required":["total_payment_attempts","failed_payments","total_collected"],"properties":{"total_payment_attempts":{"description":"The total number of invoices for which payment was attempted.","type":"integer","example":100},"failed_payments":{"description":"The number of failed payment attempts.","type":"integer","example":0},"total_collected":{"allOf":[{"description":"The total amount collected by the payment run, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]}},"title":"PaymentRunReport"},{"required":["total_notifications_sent","failed_notifications"],"properties":{"total_notifications_sent":{"description":"The total number of notifications sent.","type":"integer","example":100},"failed_notifications":{"description":"The number of failed notifications.","type":"integer","example":0}},"title":"NotificationRunReport"},{"required":["subscriptions_updated","subscription_failures","total_processed"],"properties":{"subscriptions_updated":{"description":"The total number of subscriptions updated.","type":"integer","example":100},"subscription_failures":{"description":"The total number of subscriptions that failed to be updated.","type":"integer","example":0},"total_processed":{"description":"The total number of subscriptions processed.","type":"integer","example":100}},"title":"SubscriptionUpdateReport"}],"title":"JobReport"}},"title":"JobMeta"}},"title":"Job"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a feature in an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a feature in an offering"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/features/{feature_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a feature in an offering

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"feature_uuid","in":"path","description":"The unique identifier of the feature.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the feature are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"OfferingFeature"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a plan in an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a plan in an offering"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a plan in an offering

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"plan_uuid","in":"path","description":"The unique identifier of the plan.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the plan are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a pricing option in an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a pricing option in an offering"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/pricing-options/{pricing_option_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a pricing option in an offering

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"pricing_option_uuid","in":"path","description":"The unique identifier of the pricing option.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the pricing option are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get offering"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings/{offering_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get offering

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"include","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"array","description":"A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).","example":"plans,pricing_options","items":{"type":"string","enum":["plans","pricing_options","features"]}}},{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the subscription offering are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"},"included":{"readOnly":true,"properties":{"features":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"OfferingFeature"}},"plans":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}},"pricing_options":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}},"title":"OfferingIncludes"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get proration policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get proration policy"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/proration-policies/{proration_policy_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get proration policy

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"proration_policy_uuid","in":"path","description":"The unique identifier of a proration policy.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The proration policy details are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_proration_policy","enum":["subscription_proration_policy"],"title":"ProrationPolicyType"},"attributes":{"allOf":[{"required":["name","rounding"],"properties":{"name":{"type":"string","description":"A name for the proration policy.","example":"Main Policy","minLength":3,"maxLength":1024},"rounding":{"type":"string","description":"When rounding in proration, you must decide how to round the units of time used to calculate the charges.\n\n- round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use.\n- round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use.\n- round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down.\n","enum":["up","down","nearest"],"example":"up","x-go-type":"model.ProrationPolicyRounding","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"}},"title":"ProrationPolicyAttributes"}],"title":"ProrationPolicyResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"ProrationPolicyMeta"}},"title":"ProrationPolicy"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a schedule

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a schedule"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/schedules/{schedule_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a schedule

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"schedule_uuid","in":"path","description":"The unique identifier of the schedule.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A schedule is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_schedule","enum":["subscription_schedule"],"title":"SubscriptionScheduleType"},"attributes":{"allOf":[{"required":["specification","location","job"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the schedule.","minLength":3,"maxLength":1024,"example":"Daily billing run."},"specification":{"type":"string","description":"A cron-style specification of when the jobs should be created. See [**Schedules**](/docs/api/subscriptions/schedules).","maxLength":1024,"example":"30 0 * * *"},"location":{"type":"string","description":"The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339).","maxLength":1024,"example":"Europe/London"},"job":{"required":["job_type"],"properties":{"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `payment-run` - a payment run job.\n - `notification-run` - a notification run job.\n","enum":["billing-run","payment-run","notification-run"],"example":"billing-run","x-go-type":"model.JobType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"ScheduleJobType"}},"title":"ScheduleJob"}},"title":"ScheduleAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"ScheduleResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"scheduled_for":{"type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"ScheduleMeta"}},"title":"Schedule"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a subscriber

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a subscriber"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscribers/{subscriber_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a subscriber

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscriber_uuid","in":"path","description":"The unique identifier of the subscriber.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A subscriber is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_subscriber","enum":["subscription_subscriber"],"title":"SubscriptionSubscriberType"},"attributes":{"allOf":[{"required":["name","email","account_id"],"properties":{"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"name":{"type":"string","description":"The name of the subscriber.","minLength":3,"maxLength":1024,"example":"John Doe"},"email":{"type":"string","format":"email","description":"The email of the subscriber.","minLength":3,"maxLength":1024,"example":"john.doe@example.com","x-go-type":"types.Email","x-go-type-import":{"name":"email","path":"github.com/oapi-codegen/runtime/types"}},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriberAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"SubscriberResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"feature_entitlements":{"type":"array","description":"A list of entitlement tags currently active for the subscriber","example":["tag1","tag2"],"items":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"SubscriberMeta"}},"title":"Subscriber"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a feature in a subscription

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a feature in a subscription"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/features/{feature_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a feature in a subscription

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"feature_uuid","in":"path","description":"The unique identifier of the feature.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the feature are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"OfferingFeature"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get subscription invoice payment

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get subscription invoice payment"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}/payments/{payment_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets a specific payment for a given invoice.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"payment_uuid","in":"path","description":"The unique identifier of the payment.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Specific payment for the invoice is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment`.","example":"subscription_invoice_payment","enum":["subscription_invoice_payment"],"title":"SubscriptionInvoicePaymentType"},"attributes":{"required":["success","amount","gateway"],"properties":{"success":{"type":"boolean","example":true,"description":"Whether the payment was successful."},"pending":{"type":"boolean","example":true,"description":"Whether the payment is pending (only for manual payments)."},"gateway":{"type":"string","maxLength":1024,"example":"elastic_path_payments_stripe","description":"Specifies the payment gateway."},"external_payment_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"failure_detail":{"type":"object","description":"The reason the payment failed.","properties":{"reason":{"type":"string","example":"Card Failure"}},"title":"PaymentFailureDetail"},"amount":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"}},"title":"SubscriptionInvoicePaymentAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps","invoice_id","subscription_id","job_id","manual_payment"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"job_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"payment_taken_at":{"description":"The date and time a payment was taken.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoicePaymentTimestamps"},"manual_payment":{"type":"boolean","example":false,"description":"Whether manual payments are enabled or the payment will be handled by the configured gateway."}},"title":"SubscriptionInvoicePaymentMeta"}},"title":"SubscriptionInvoicePayment"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get subscription invoice

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get subscription invoice"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Gets a specific invoice for a given subscription.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. An invoice is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"description":"This represents the type of resource object being returned. Always `subscription_invoice`.","type":"string","example":"subscription_invoice","enum":["subscription_invoice"],"title":"SubscriptionInvoiceType"},"attributes":{"required":["billing_period","pro_forma","invoice_items","outstanding","tax_required","payment_retries_limit_reached","manual_payment_pending"],"properties":{"billing_period":{"description":"A period of time between a start and end point.","required":["start","end"],"properties":{"start":{"description":"The date and time a billing period started.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"end":{"description":"The date and time a billing period ended.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"TimePeriod"},"invoice_items":{"type":"array","items":{"required":["description","price"],"properties":{"description":{"type":"string","description":"A description of the subscribed item.","example":"Magazine issue"},"price":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"from_time_period":{"description":"The start date and time of the billing period in this price","type":"string","example":"2017-01-10T11:41:19.244842Z"},"until_time_period":{"description":"The end date and time of the billing period in this price","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionInvoiceItem"}},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}},"outstanding":{"type":"boolean","description":"The invoice still requires payment if `true`.","example":true},"number":{"type":"integer","description":"A sequential number assigned by the billing run.","example":1},"tax_required":{"type":"boolean","description":"Whether tax is required for this invoice.","example":true},"payment_retries_limit_reached":{"type":"boolean","description":"Whether the limit of payment retries has been reached.","example":false},"updated_at":{"description":"The date and time an invoice was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time an invoice was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pro_forma":{"description":"Whether the invoice is a Pro Forma invoice (generated ahead of payment) or not.\n\nPro Forma Invoices are created ahead of payment time (for example, a week in advance of payment so\nyou can notify customers) and will not be picked up by a payment run until on or after their valid_from\ndate.\n","type":"boolean","example":false},"valid_from":{"description":"The date and time at which an invoice will be valid from.\n\nIf generated with no lead time then the invoice will be valid immediately.\n\nIf generated with a lead time, then the valid_from will be the data at which the Invoice transitions from\nit's Pro Forma state to one that can have payment taken.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"manual_payment_pending":{"type":"boolean","description":"Whether there is a manual pending payment pending on the invoice.","example":true}},"title":"SubscriptionInvoiceAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","proration_events","pro_rata_remaining_value","display_price"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"subscriber_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"price":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice","description":"Invoice totals formatted for display (`with_tax`, `without_tax`, `tax`). Amounts are in the\ncurrency's smallest subdivision.\n"},"notifications":{"description":"A list of notifications scheduled for this invoice. These are derived from the notification\nschedules configured on the pricing option at the time the invoice was created. Each notification\nhas a due date calculated relative to the billing period end date.\n","type":"array","items":{"description":"A notification scheduled for an invoice.","required":["name","due"],"properties":{"name":{"description":"The name of the notification schedule that generated this notification.","type":"string","example":"7 days before renewal"},"due":{"description":"The date and time when the notification is due to be sent.","type":"string","format":"date-time","example":"2024-01-24T00:00:00Z"},"sent_at":{"description":"The date and time when the notification was sent.","type":"string","format":"date-time","example":"2024-01-24T00:00:00Z"}},"title":"InvoiceNotification"}},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"taxes_added_at":{"description":"The date and time taxes were added to an invoice.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoiceTimestamps"},"proration_events":{"type":"array","items":{"required":["proration_policy_id","billing_cost_before_proration","refunded_amount_for_unused_pricing_option","new_pricing_option_cost","prorated_at"],"properties":{"proration_policy_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"billing_cost_before_proration":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision","example":100},"refunded_amount_for_unused_pricing_option":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"new_pricing_option_cost":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"prorated_at":{"description":"The date and time the subscription was prorated.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"ProrationEvent"}},"pro_rata_remaining_value":{"type":"integer","format":"int64","description":"The pro-rated remaining value for the billing period","example":500}},"title":"SubscriptionInvoiceMeta"}},"title":"SubscriptionInvoice"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a plan in a subscription

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a plan in a subscription"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/plans/{plan_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a plan in a subscription

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"plan_uuid","in":"path","description":"The unique identifier of the plan.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the plan are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get a pricing option in a subscription

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a pricing option in a subscription"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/pricing-options/{pricing_option_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a pricing option in a subscription

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"pricing_option_uuid","in":"path","description":"The unique identifier of the pricing option.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the pricing option are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get subscription state

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get subscription state"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/states/{state_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get subscription state

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"state_uuid","in":"path","description":"The unique identifier of the subscription state.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A subscription state is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_state`.","example":"subscription_state","enum":["subscription_state"],"title":"SubscriptionStateType"},"attributes":{"required":["action"],"properties":{"action":{"type":"string","description":"The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n","example":"cancel","enum":["cancel","pause","resume","pending"],"x-go-type":"model.SubscriptionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"SubscriptionStateAction"},"cancel_immediately":{"type":"boolean","default":false,"example":false,"description":"When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n"}},"title":"SubscriptionStateAttributes"},"meta":{"readOnly":true,"required":["created_at"],"properties":{"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"StateMeta"}},"title":"SubscriptionState"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Get subscription

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get subscription"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get subscription

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"include","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"array","description":"A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).","example":"plans,pricing_options","items":{"type":"string","enum":["plans","pricing_options"]}}},{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of a subscription are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription","enum":["subscription"],"title":"SubscriptionType"},"attributes":{"required":["account_id","pricing_option_id","plan_id","offering","currency","name","email"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"address_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"offering":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"},"pricing_option_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"currency":{"type":"string","description":"The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase.","maxLength":1024,"example":"USD","title":"CurrencyIdentifier"},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriptionAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","status","canceled","paused","closed","pending","suspended","invoice_after","manual_payments","first_invoice_prepaid"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"canceled_at":{"description":"The date and time a subscription was cancelled.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"paused_at":{"description":"The date and time a subscription was paused.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"resumed_at":{"description":"The date and time a subscription was resumed.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"end_date":{"description":"The date and time a subscription will end.\n- If the subscription offering pricing option end behavior is `close`, `end_date` is set to the billing period end date upon subscription creation.\n- If the subscription offering pricing option end behavior is \"roll\": `end_date` is set to the billing period end date when the subscription is cancelled.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live_after":{"description":"The date and time a subscription will go live and become active.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live":{"description":"The date and time a subscription was released from the pending state and made active.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"SubscriptionTimestamps"},"status":{"type":"string","description":"The status of a subscription, either `active` or `inactive`.","example":"active","enum":["active","inactive"],"x-go-type":"model.SubscriptionStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"Status"},"state":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_state`.","example":"subscription_state","enum":["subscription_state"],"title":"SubscriptionStateType"},"attributes":{"required":["action"],"properties":{"action":{"type":"string","description":"The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n","example":"cancel","enum":["cancel","pause","resume","pending"],"x-go-type":"model.SubscriptionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"SubscriptionStateAction"},"cancel_immediately":{"type":"boolean","default":false,"example":false,"description":"When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n"}},"title":"SubscriptionStateAttributes"},"meta":{"readOnly":true,"required":["created_at"],"properties":{"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"StateMeta"}},"title":"SubscriptionState"},"manual_payments":{"type":"boolean","example":false,"default":false,"description":"When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments).","title":"ManualPayments"},"first_invoice_prepaid":{"type":"boolean","description":"Indicates that the first billing period of this subscription was paid for outside of the subscriptions service.","example":false},"canceled":{"type":"boolean","description":"Whether a subscription is canceled or not.","example":true},"paused":{"type":"boolean","description":"Whether a subscription is paused or not.","example":true},"closed":{"type":"boolean","description":"Whether a subscription is closed or not.","example":true},"suspended":{"type":"boolean","description":"Whether a subscription is suspended or not.","example":false},"pending":{"type":"boolean","description":"Whether a subscription is pending activation or not.","example":false},"invoice_after":{"description":"The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pending_price_change":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"price_update_history":{"description":"A history of price updates that have been applied to this subscription.","type":"array","x-go-type-skip-optional-pointer":true,"items":{"description":"A record of the previous prices of a subscription before a price change was applied","required":["price_changes","valid_until"],"properties":{"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"valid_until":{"description":"The date and time when the prices were changed (when these previous prices stopped being active)","type":"string","format":"date-time","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionPriceUpdateHistoryEntry"}}},"title":"SubscriptionMeta"}},"title":"Subscription"},"included":{"readOnly":true,"properties":{"plans":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}},"pricing_options":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}},"title":"SubscriptionIncludes"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Imports(Subscriptions)

You can import subscription features, subscribers, offerings and subscriptions using Subscriptions Import. This is useful if you want to import subscriptions from an external system into Elastic Path Subscriptions. 

The API uses a [**JSONL**](https://jsonlines.org/) file. Here is an [**example of a JSONL file**](/assets/subscriptions_import.jsonl).

When you send an import request, an import job is created. Jobs are processed one at a time. You can continue to send import requests, but those jobs are queued. In other words, Subscriptions looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. Use [List import jobs](/docs/api/subscriptions/list-import-jobs) to see a list of all import jobs.

A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time.

### Characteristics of Subscriptions Import

The Subscriptions Import API has the following characteristics:

- The Subscriptions Import API reads the entire file and then creates the subscription objects. This means the subscription objects can be in any order in the file.

- Subscriptions imports are asynchronous and are processed one at a time. You can continue to send import requests, but these are queued. 

- The API works on a "best endeavours" approach. In other words, the API does its best to create the subscription objects based on the file that you provide. 

### Subscriptions Import File

The following table describes the subscriptions objects, and their attributes, that the import file can include.

| Object | Attributes |
| --- | --- |
| A subscriber object | The attributes you specify for a subscriber object are the attributes you specify when [creating a subscriber](/docs/api/subscriptions/create-subscriber). |
| An offering object | The attributes you specify for an offering object are the attributes you specify when [building an offering](/docs/api/subscriptions/build-offering). |

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Invoices

Invoices represent the amount a customer owes for a subscription. Elastic Path Subscriptions generates an invoice for every period in a subscription billing cycle. Invoices provide:

- an itemized list of goods and services provided by a subscription.
- the cost of a subscription.
- if applicable, any taxes.

The invoice lifecycle is described below.

1. When a subscription is created, an invoice for the first billing period is created. When a subscription is created as part of an order, the payment for the order covers the first billing period.
2. Subscription invoices are created by [**billing runs**](/docs/api/subscriptions/jobs). The billing run identifies subscriptions that require a new invoice for their next billing period and creates them. At this point, invoices are marked as outstanding.
3. Invoices where `tax_required` is `true` will not have payment taken until a tax run has added the required tax to the invoice.  
3. The [**payment run**](/docs/api/subscriptions/jobs) identifies invoices that are still outstanding and attempts to take payment for them. If the payment succeeds the the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment. If an invoice has a failed payment, payment is only retried if the fixed interval has passed from the last payment attempt as defined in Settings.

### Payment Retries

It is important to limit the number of times Subscriptions retries a failed payment request for many reasons, including: frequent payment retries can indicate fraudulent activities; multiple failed payment attempts can lead to customers accounts being locked out or flagged for suspicious activity resulting in poor customer experience; and excessive retries places an unnecessary load on your payment processing system.

In Subscriptions, by default, the number of payment retries is 10. You can set this to a limit between 0 - 20, depending on your requirements. Each payment retry is made as a payment run. 

Once the number of payment retries reaches the limit, the payment retries stop, resulting in status of the invoice being unpaid. See [Invoices](#invoices).

When configuring payment retries, you have the following options.

| Attribute | Required | Description |
| --- | --- | --- |
| `payment_retry_type` | Optional | One of the following options: `fixed` - use `fixed` if you want a fixed time interval between payment retries.`backoff` - use `backoff` if you want the time between retry attempts to increase exponentially.`tiered` - use `tiered` if you want to specify a list of time durations.  |
| `payment_retry_interval` | Optional | Represents the retry interval. For example, if `payment_retry_unit` is `week` and `payment_retry_interval` is `1` then, the payment retry interval is 1 week.  |
| `payment_retry_multiplier` | Optional | Use when `payment_retry_type` is `tiered` and represents the factor by which the time duration increases after each retry.   |
| `payment_retry_unit` | Optional | Represents the unit of time, either `day` or `week`. |

### Rounding

Subscriptions always rounds down to the penny. 

### Tax

Subscriptions allows you to apply any number of tax rates to your invoices and subscriptions. When applying a tax rate, you must specify:

- a name that appears on your customer's invoice that describes the specific type of tax.
- the tax rate which is the percentage of the subscription amount that is required to be paid as tax.

In addition, you can optionally specify the jurisdiction which is the geographic area or political entity that has authority to levey and collect taxes.

You can apply more than one tax rate for all items in an invoice. You cannot apply a tax rate per line item.

### Payments

When your customers add a subscription to a cart and the cart is checked out, an unpaid order is returned. You can process the payment for the order though a payment gateway. You can do this using:

- Elastic Path Payments Powered by Stripe. The Elastic Path Payments Powered by Stripe gateway interacts with Stripe to allow your subscribers to pay for their subscriptions. 
- Authorize.Net. 

#### Using Elastic Path Payments Powered by Stripe

To use Elastic Path Payments Powered by Stripe gateway, contact the [**Customer Success Team**](mailto:customersuccess@elasticpath.com). 

Create your Stripe account in [**Stripe Dashboard**](https://dashboard.stripe.com/login) and complete an onboarding form to make payments using the gateway. For more information, see [**Onboarding**](/docs/payments/onboarding).

Once you have signed up for Elastic Path Payments Powered by Stripe, you must configure the payment gateway so that your shoppers can make payments. See [**Configure Elastic Path Payments Powered by Stripe**](/docs/payments/onboarding).

#### Using Authorize.Net

To use Authorize.Net, you must have: 

- an active merchant account with Authorize.Net
- obtained API credentials. These include an **API Login ID** and a **Transaction Key**.
- Enabled Authorize.Net in Commerce Manager. See [Enabling Authorize.net](/docs/commerce-manager/payments/configure-other-payment-gateways#enabling-authorizenet).

#### Payment Requests

Subscriptions only supports the `purchase` payment mechanism. The gateway attempts to charge the customer immediately, and the result of the attempt is returned. If a payment fails, the invoice is kept as outstanding and the payment information, with the reason for the failure is attached to the invoice. A new payment run is required to attempt another payment. 

When sending a payment request to the Payments service, you must specify the following.

| Attribute | Required | Description |
| --- | --- | --- |
| `gateway` | Required| One of `elastic_path_payments_stripe`, `authorize_net` and `stripe_payment_intents`. |
| `method` | Required | Must be `purchase`.
| `payment` | Required | The type of payment, for example, `pm_card_visa_debit`.
| `options` | Required | These options must be set as they set up the card to be used in future without the customer being present. If these options are not set, future payments may fail. There are two options. `off_session`. Must be set to `true`. `confirm`. Must be set to `true`. |

#### External Payments

External payments are payment methods not offered by Elastic Path Subscriptions (such as Elastic Path Payments powered by Stripe or Authorize.net), but they can still be integrated with Subscriptions. To do this, you must configure your subscriptions to use external payments by setting `manual_payments` to `true`. See [Create a Subscription](/docs/api/subscriptions/create-subscription).

When a subscription is created with `manual_payments` set to `true`:

1. When the payment run processes the generated invoice, it creates a pending payment. A `subscription-invoice-created` event is emitted that includes the `subscription_id`, `invoice_id` and `payment_id`. No payment is taken. 
2. You can use the events generated by Elastic Path Subscriptions to configure your external payment system to respond to these events, ensuring that your external payment system knows when the payment schedule has run and it's time to process the payment.
3. When the external payment system handles the payment (either takes the payment successfully or the payment fails) the [Update Invoice Payment](/docs/api/subscriptions/update-invoice-payment) endpoint, enables the update of the pending payment. 
    - If payment is successful, the invoice is updated to `paid` and the billing/payment cycle continues as normal.
    - If payment fails, the invoice continues to be marked as `outstanding`. The payment is not `pending` anymore. This is because a payment attempt has been made. Following on from this, the next payment run generates another manual pending payment. The external system is notified of this using the `subscription-invoice-payment-updated`.

#### Card Declines

Card payments can fail for a variety of reasons, including insufficient funds, incorrect card data or fraudulent activity. You can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details, enabling you to easily manage your subscription changes.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Jobs(Subscriptions)

Jobs are an asynchronous process that can be triggered manually or scheduled. 

There are three types of job:

- a billing run. Subscriptions generates an [**invoice**](/docs/api/subscriptions/invoices) when a billing run occurs. Billing runs generate invoices for the remaining billing cycles for each subscription. The invoice dates come from your pricing options. Billing runs are independent of payment runs.
- a tax run. Invoices where `tax_required` is `true` will not have payment taken until a tax run has added the required tax to the invoice.
- a payment run. The payment run identifies invoices that are outstanding and attempts to take payment for them. If the payment succeeds the the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment.

By scheduling billing and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner. See [**Schedules**](/docs/api/subscriptions/schedules).

### Characteristics of Billing, Tax & Payments Jobs

Billing and payment jobs have the following characteristics.

- Jobs are asynchronous.
- Jobs have a different status, depending on where a job is in its lifecycle.
- Jobs report any errors to help you understand the reason for any failed jobs.
- Only one billing run and payment run is allowed per store at a time. Although billing and payments are constantly generated, the jobs are queued. Subscriptions looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed.

### Billing, Tax & Payments Jobs Lifecycle

A job can have the following status types:

- PENDING - Subscriptions has received the request but is currently busy processing other requests.
- STARTED - Subscriptions has started processing the job.
- SUCCESS - The job has successfully completed.
- FAILED - The job has failed.

### Billing, Tax & Payment Reports

You can track your Subscriptions billing, payment and tax operations using reports. There are three types of report:

- `BillingRunReport` - This report provides invoice summaries such as invoices ready for payment, invoices that require tax, and invoice failures.
- `TaxRunReport` - This report provides invoice summaries such as invoices to which tax was successfully or unsuccessfully added.
- `PaymentRunReport` - This report provides invoice summaries such as invoices for which payment was attempted, failed payment attempts and totals collected by a payment run. 
- `NotificationRunReport` - This report provides notification summaries such as notifications sent and failed to send.
- `SubscriptionUpdateReport` - This report provides subscription update summaries such as subscriptions that were updated successfully and failed updates.

See [Get a job](/docs/api/subscriptions/get-job) and [List jobs](/docs/api/subscriptions/list-jobs).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## List dunning rules

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List dunning rules"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/dunning-rules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all dunning rule sets.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}},{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of dunning rules is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_dunning_rule","enum":["subscription_dunning_rule"],"title":"SubscriptionDunningRuleType"},"attributes":{"description":"The dunning rule attributes you can use to configure your payment retry strategy.\n","example":{"payment_retry_type":"fixed","payment_retry_unit":"day","payment_retry_interval":1,"payment_retries_limit":10,"action":"none"},"required":["payment_retry_type","payment_retries_limit","action"],"properties":{"payment_retry_type":{"type":"string","enum":["fixed","backoff","tiered"],"example":"fixed","description":"The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.\n","x-go-type":"model.PaymentRetryType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_interval":{"type":"integer","format":"int64","minimum":1,"maximum":1024,"example":1,"description":"The number of `payment_interval_unit`s to wait between each payment retry attempt."},"payment_retry_unit":{"type":"string","enum":["day","week"],"example":"day","description":"The unit of time used to measure the intervals between payment attempts or retries.","x-go-type":"model.PaymentRetryUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_multiplier":{"type":"number","format":"double","minimum":1,"maximum":1024,"example":1,"description":"The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types."},"payment_retries_limit":{"type":"integer","format":"int64","minimum":0,"example":5,"description":"The number of times Subscriptions attempts payment retries before `action` is taken."},"action":{"type":"string","enum":["none","pause","close","suspend"],"example":"none","description":"The action to take after all payment attempts for an invoice have failed.\n\n- None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.\n- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.\n- close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.\n","x-go-type":"model.DunningAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"default":{"type":"boolean","example":false,"description":"Set to `true` if you want this rule to be the default for the store."}},"title":"DunningRuleAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"DunningRuleMeta"}},"title":"DunningRule"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List features

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List features"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/features"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all subscription features.

### Filtering

This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator | Attribute | Description |
| --- | --- | --- | 
| `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
| `eq` | `tag` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
| `in` | `external_ref`, `tag` | In. Checks if the value is in the specified list. If it is, the condition is true. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of features is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_feature","enum":["subscription_feature"],"title":"SubscriptionFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"Feature"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List import jobs(Subscriptions)

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List import jobs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/imports"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all import jobs.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of import jobs is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","meta","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_import","enum":["subscription_import"],"title":"SubscriptionImportType"},"attributes":{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.\n- **pending** - Commerce has received the request but is currently busy processing other requests.\n- **started** - Commerce has started processing the job.\n- **success** - The job has successfully completed.\n- **failed** - The job has failed.\n","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}}},"title":"ImportAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps","records"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"records":{"type":"object","description":"You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported into Subscriptions. However, this does not mean they are valid subscription objects, only that they have the correct type and their JSON format is properly formatted. Imported shows the number of records that have been both validated and successfully added to Subscriptions.","required":["uploaded","imported"],"properties":{"uploaded":{"type":"object","properties":{"subscription_feature":{"description":"The total number of features uploaded.","type":"integer","example":50000},"subscription_subscriber":{"description":"The total number of subscribers uploaded.","type":"integer","example":50000},"subscription_offering":{"description":"The total number of offerings uploaded.","type":"integer","example":50000},"subscription":{"description":"The total number of subscriptions uploaded.","type":"integer","example":50000}},"required":["subscription_feature","subscription_subscriber","subscription_offering","subscription"]},"imported":{"properties":{"subscription_feature":{"description":"The total number of features uploaded.","type":"integer","example":50000},"subscription_subscriber":{"description":"The total number of subscribers imported.","type":"integer","example":45090},"subscription_offering":{"description":"The total number of offerings imported.","type":"integer","example":45090},"subscription":{"description":"The total number of subscriptions imported.","type":"integer","example":45090}},"required":["subscription_feature","subscription_subscriber","subscription_offering","subscription"]}},"title":"ImportRecords"}},"title":"ImportMeta"}},"title":"Import"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List invoice payment refunds

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List invoice payment refunds"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}/refunds"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all refunds for an invoice payments

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"payment_uuid","in":"path","description":"The unique identifier of the payment.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Refunds for an invoice payment are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["id","type","attributes","relationships"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment_refund`.","example":"subscription_invoice_payment_refund","enum":["subscription_invoice_payment_refund"],"title":"SubscriptionInvoicePaymentRefundType"},"attributes":{"required":["amount","reason","gateway","external_refund_id","created_at"],"properties":{"amount":{"type":"integer","format":"int64","minimum":1,"description":"The value as a whole number of the currency's smallest subdivision.","example":100},"reason":{"type":"string","maxLength":1024,"description":"The reason or note for the refund","example":"Customer requested cancellation"},"gateway":{"type":"string","maxLength":1024,"example":"elastic_path_payments_stripe","description":"Specifies the payment gateway."},"external_refund_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionInvoicePaymentRefundAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"}},"title":"SubscriptionInvoicePaymentRefund"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List invoice payments

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List invoice payments"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/invoices/{invoice_uuid}/payments"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List invoice payments

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Payments for the invoice are returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment`.","example":"subscription_invoice_payment","enum":["subscription_invoice_payment"],"title":"SubscriptionInvoicePaymentType"},"attributes":{"required":["success","amount","gateway"],"properties":{"success":{"type":"boolean","example":true,"description":"Whether the payment was successful."},"pending":{"type":"boolean","example":true,"description":"Whether the payment is pending (only for manual payments)."},"gateway":{"type":"string","maxLength":1024,"example":"elastic_path_payments_stripe","description":"Specifies the payment gateway."},"external_payment_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"failure_detail":{"type":"object","description":"The reason the payment failed.","properties":{"reason":{"type":"string","example":"Card Failure"}},"title":"PaymentFailureDetail"},"amount":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"}},"title":"SubscriptionInvoicePaymentAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps","invoice_id","subscription_id","job_id","manual_payment"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"job_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"payment_taken_at":{"description":"The date and time a payment was taken.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoicePaymentTimestamps"},"manual_payment":{"type":"boolean","example":false,"description":"Whether manual payments are enabled or the payment will be handled by the configured gateway."}},"title":"SubscriptionInvoicePaymentMeta"}},"title":"SubscriptionInvoicePayment"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}}}}
>
  
</StatusCodes>

---

## List invoices

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List invoices"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/invoices"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all invoices.

### Filtering

This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator |Attribute | Description |
| --- | --- | --- | 
| `eq` | `subscriber_id`, `subscription_id`, `outstanding`, `tax_required` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
| `in` | `subscriber_id`, `subscription_id` | In. Checks if the value is in the specified list. If it is, the condition is true. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}},{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of invoices is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"description":"This represents the type of resource object being returned. Always `subscription_invoice`.","type":"string","example":"subscription_invoice","enum":["subscription_invoice"],"title":"SubscriptionInvoiceType"},"attributes":{"required":["billing_period","pro_forma","invoice_items","outstanding","tax_required","payment_retries_limit_reached","manual_payment_pending"],"properties":{"billing_period":{"description":"A period of time between a start and end point.","required":["start","end"],"properties":{"start":{"description":"The date and time a billing period started.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"end":{"description":"The date and time a billing period ended.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"TimePeriod"},"invoice_items":{"type":"array","items":{"required":["description","price"],"properties":{"description":{"type":"string","description":"A description of the subscribed item.","example":"Magazine issue"},"price":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"from_time_period":{"description":"The start date and time of the billing period in this price","type":"string","example":"2017-01-10T11:41:19.244842Z"},"until_time_period":{"description":"The end date and time of the billing period in this price","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionInvoiceItem"}},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}},"outstanding":{"type":"boolean","description":"The invoice still requires payment if `true`.","example":true},"number":{"type":"integer","description":"A sequential number assigned by the billing run.","example":1},"tax_required":{"type":"boolean","description":"Whether tax is required for this invoice.","example":true},"payment_retries_limit_reached":{"type":"boolean","description":"Whether the limit of payment retries has been reached.","example":false},"updated_at":{"description":"The date and time an invoice was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time an invoice was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pro_forma":{"description":"Whether the invoice is a Pro Forma invoice (generated ahead of payment) or not.\n\nPro Forma Invoices are created ahead of payment time (for example, a week in advance of payment so\nyou can notify customers) and will not be picked up by a payment run until on or after their valid_from\ndate.\n","type":"boolean","example":false},"valid_from":{"description":"The date and time at which an invoice will be valid from.\n\nIf generated with no lead time then the invoice will be valid immediately.\n\nIf generated with a lead time, then the valid_from will be the data at which the Invoice transitions from\nit's Pro Forma state to one that can have payment taken.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"manual_payment_pending":{"type":"boolean","description":"Whether there is a manual pending payment pending on the invoice.","example":true}},"title":"SubscriptionInvoiceAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","proration_events","pro_rata_remaining_value","display_price"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"subscriber_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"price":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice","description":"Invoice totals formatted for display (`with_tax`, `without_tax`, `tax`). Amounts are in the\ncurrency's smallest subdivision.\n"},"notifications":{"description":"A list of notifications scheduled for this invoice. These are derived from the notification\nschedules configured on the pricing option at the time the invoice was created. Each notification\nhas a due date calculated relative to the billing period end date.\n","type":"array","items":{"description":"A notification scheduled for an invoice.","required":["name","due"],"properties":{"name":{"description":"The name of the notification schedule that generated this notification.","type":"string","example":"7 days before renewal"},"due":{"description":"The date and time when the notification is due to be sent.","type":"string","format":"date-time","example":"2024-01-24T00:00:00Z"},"sent_at":{"description":"The date and time when the notification was sent.","type":"string","format":"date-time","example":"2024-01-24T00:00:00Z"}},"title":"InvoiceNotification"}},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"taxes_added_at":{"description":"The date and time taxes were added to an invoice.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoiceTimestamps"},"proration_events":{"type":"array","items":{"required":["proration_policy_id","billing_cost_before_proration","refunded_amount_for_unused_pricing_option","new_pricing_option_cost","prorated_at"],"properties":{"proration_policy_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"billing_cost_before_proration":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision","example":100},"refunded_amount_for_unused_pricing_option":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"new_pricing_option_cost":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"prorated_at":{"description":"The date and time the subscription was prorated.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"ProrationEvent"}},"pro_rata_remaining_value":{"type":"integer","format":"int64","description":"The pro-rated remaining value for the billing period","example":500}},"title":"SubscriptionInvoiceMeta"}},"title":"SubscriptionInvoice"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List jobs

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List jobs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/jobs"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all jobs.

### Filtering

This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator | Attribute | Description |
| --- | --- | --- | 
| `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
| `in` | `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of jobs is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_job","enum":["subscription_job"],"title":"SubscriptionJobType"},"attributes":{"allOf":[{"required":["job_type"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `tax-run` - a tax run job.\n - `payment-run` - a payment run job.\n - `import` - an import job.\n - `notification-run` - a notification run job.\n - `subscription-update` - a subscription update run job.\n","enum":["billing-run","tax-run","payment-run","import","notification-run","subscription-update"],"example":"billing-run","x-go-type":"string"}},"oneOf":[{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"billing-run"}},"title":"BillingRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"tax-run"},"taxes":{"type":"array","minItems":1,"items":{"required":["invoice_id","tax_items"],"properties":{"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}}},"title":"InvoiceTaxItems"}}},"title":"TaxRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"payment-run"}},"title":"PaymentRunJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"import"}},"title":"ImportJobAttributes"},{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"notification-run"}},"title":"NotificationRunJobAttributes"},{"required":["job_type","price_changes"],"properties":{"job_type":{"type":"string","example":"subscription-update"},"offering_id":{"description":"The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555"},"excluded_subscription_ids":{"description":"Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"subscription_ids":{"description":"Specific subscriptions to update. Mutually exclusive with `offering_id`.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"}},"title":"SubscriptionUpdateRunJobAttributes"}],"discriminator":{"propertyName":"job_type","mapping":{"billing-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"billing-run"}},"title":"BillingRunJobAttributes"},"tax-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"tax-run"},"taxes":{"type":"array","minItems":1,"items":{"required":["invoice_id","tax_items"],"properties":{"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}}},"title":"InvoiceTaxItems"}}},"title":"TaxRunJobAttributes"},"payment-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"payment-run"}},"title":"PaymentRunJobAttributes"},"import":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"import"}},"title":"ImportJobAttributes"},"notification-run":{"required":["job_type"],"properties":{"job_type":{"type":"string","example":"notification-run"}},"title":"NotificationRunJobAttributes"},"subscription-update":{"required":["job_type","price_changes"],"properties":{"job_type":{"type":"string","example":"subscription-update"},"offering_id":{"description":"The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n","type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555"},"excluded_subscription_ids":{"description":"Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"subscription_ids":{"description":"Specific subscriptions to update. Mutually exclusive with `offering_id`.\n","type":"array","items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"x-go-type-skip-optional-pointer":true},"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"}},"title":"SubscriptionUpdateRunJobAttributes"}}},"title":"JobCreateAttributes"},{"required":["status"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"status":{"type":"string","description":"The status of job.","enum":["pending","started","success","failed"],"example":"pending","x-go-type":"model.JobStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}}},"title":"JobAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"JobResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"started_at":{"description":"The date and time a job is started.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"finished_at":{"description":"The date and time a job finished.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"JobTimestamps"},"report":{"description":"You can track your Subscriptions billing, tax, and payment operations using reports.","oneOf":[{"required":["invoices_ready_for_payment","invoices_tax_required","invoice_failures","total_ready_for_payment","total_tax_required"],"properties":{"invoices_ready_for_payment":{"description":"The total number of invoices created that are ready for payment.","type":"integer","example":100},"invoices_tax_required":{"description":"The total number of invoices created that need taxes to be applied before payment can be made.","type":"integer","example":100},"invoice_failures":{"description":"The total number of invoices that were scheduled but creation failed.","type":"integer","example":0},"total_ready_for_payment":{"allOf":[{"description":"The total amount ready for payment invoiced in the billing run, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]},"total_tax_required":{"allOf":[{"description":"The total amount (excluding tax) invoiced in the billing run but still requiring taxes, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]}},"title":"BillingRunReport"},{"required":["invoices_updated","invoice_failures"],"properties":{"invoices_updated":{"description":"The total number of invoices to which tax was successfully added.","type":"integer","example":100},"invoice_failures":{"description":"The total number of invoices to which tax could not be added.","type":"integer","example":0}},"title":"TaxRunReport"},{"required":["total_payment_attempts","failed_payments","total_collected"],"properties":{"total_payment_attempts":{"description":"The total number of invoices for which payment was attempted.","type":"integer","example":100},"failed_payments":{"description":"The number of failed payment attempts.","type":"integer","example":0},"total_collected":{"allOf":[{"description":"The total amount collected by the payment run, segmented by currency."},{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}]}},"title":"PaymentRunReport"},{"required":["total_notifications_sent","failed_notifications"],"properties":{"total_notifications_sent":{"description":"The total number of notifications sent.","type":"integer","example":100},"failed_notifications":{"description":"The number of failed notifications.","type":"integer","example":0}},"title":"NotificationRunReport"},{"required":["subscriptions_updated","subscription_failures","total_processed"],"properties":{"subscriptions_updated":{"description":"The total number of subscriptions updated.","type":"integer","example":100},"subscription_failures":{"description":"The total number of subscriptions that failed to be updated.","type":"integer","example":0},"total_processed":{"description":"The total number of subscriptions processed.","type":"integer","example":100}},"title":"SubscriptionUpdateReport"}],"title":"JobReport"}},"title":"JobMeta"}},"title":"Job"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List an offering's features

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List an offering's features"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/features"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List an offering's features

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of subscription features attached to the offering is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"OfferingFeature"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List the pricing options available to a plan in an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List the pricing options available to a plan in an offering"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}/relationships/pricing_options"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List the pricing options available to a plan in an offering

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"plan_uuid","in":"path","description":"The unique identifier of the plan.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The pricing option relationships are returned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List an offering's plans

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List an offering's plans"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/plans"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List an offering's plans

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of subscription plans attached to the offering is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List an offering's pricing options

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List an offering's pricing options"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/pricing-options"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List an offering's pricing options

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of pricing options attached with the offering is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List offerings

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List offerings"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/offerings"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all subscription offerings.

### Filtering

This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator | Attribute | Description |
| --- | --- | --- | 
| `eq` | `external_ref`, `plans.external_ref`, `proration_policy_id` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
| `in` | `external_ref`, `plans.external_ref`, `proration_policy_id` | In. Checks if the value is in the specified list. If it is, the condition is true. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"include","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"array","description":"A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).","example":"plans,pricing_options","items":{"type":"string","enum":["plans","pricing_options","features"]}}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of offerings is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"}},"included":{"readOnly":true,"properties":{"features":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"OfferingFeature"}},"plans":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}},"pricing_options":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}},"title":"OfferingIncludes"},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List proration policies

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List proration policies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/proration-policies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all proration policies.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of proration policies is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_proration_policy","enum":["subscription_proration_policy"],"title":"ProrationPolicyType"},"attributes":{"allOf":[{"required":["name","rounding"],"properties":{"name":{"type":"string","description":"A name for the proration policy.","example":"Main Policy","minLength":3,"maxLength":1024},"rounding":{"type":"string","description":"When rounding in proration, you must decide how to round the units of time used to calculate the charges.\n\n- round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use.\n- round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use.\n- round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down.\n","enum":["up","down","nearest"],"example":"up","x-go-type":"model.ProrationPolicyRounding","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"}},"title":"ProrationPolicyAttributes"}],"title":"ProrationPolicyResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"ProrationPolicyMeta"}},"title":"ProrationPolicy"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List schedules

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List schedules"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/schedules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all schedules.

### Filtering

This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator | Attribute | Description |
| --- | --- | --- | 
| `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
| `in` | `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of schedules is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_schedule","enum":["subscription_schedule"],"title":"SubscriptionScheduleType"},"attributes":{"allOf":[{"required":["specification","location","job"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the schedule.","minLength":3,"maxLength":1024,"example":"Daily billing run."},"specification":{"type":"string","description":"A cron-style specification of when the jobs should be created. See [**Schedules**](/docs/api/subscriptions/schedules).","maxLength":1024,"example":"30 0 * * *"},"location":{"type":"string","description":"The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339).","maxLength":1024,"example":"Europe/London"},"job":{"required":["job_type"],"properties":{"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `payment-run` - a payment run job.\n - `notification-run` - a notification run job.\n","enum":["billing-run","payment-run","notification-run"],"example":"billing-run","x-go-type":"model.JobType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"ScheduleJobType"}},"title":"ScheduleJob"}},"title":"ScheduleAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"ScheduleResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"scheduled_for":{"type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"ScheduleMeta"}},"title":"Schedule"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List subscribers

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List subscribers"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscribers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all subscribers.

### Filtering

This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator | Attribute | Description |
| --- | --- | --- | 
| `eq` | `account_id`, `name`, `email`, `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
| `in` | `account_id`, `name`, `email`, `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. |
| `like` | `name`, `email` | Partial match (case-sensitive). Use `*` at the start, end, or both to match any sequence of characters (e.g. `*substring`, `substring*`, `*substring*`). |
| `ilike` | `name`, `email` | Partial match (case-insensitive). Same as `like` but matching ignores case. Use `*` at the start, end, or both to match any sequence of characters. |

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of subscribers is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_subscriber","enum":["subscription_subscriber"],"title":"SubscriptionSubscriberType"},"attributes":{"allOf":[{"required":["name","email","account_id"],"properties":{"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"name":{"type":"string","description":"The name of the subscriber.","minLength":3,"maxLength":1024,"example":"John Doe"},"email":{"type":"string","format":"email","description":"The email of the subscriber.","minLength":3,"maxLength":1024,"example":"john.doe@example.com","x-go-type":"types.Email","x-go-type-import":{"name":"email","path":"github.com/oapi-codegen/runtime/types"}},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriberAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"SubscriberResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"feature_entitlements":{"type":"array","description":"A list of entitlement tags currently active for the subscriber","example":["tag1","tag2"],"items":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"SubscriberMeta"}},"title":"Subscriber"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List an subscriptions features

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List an subscriptions features"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/features"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List an subscriptions features

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of subscription features is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"OfferingFeature"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List subscription invoice payments

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List subscription invoice payments"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/invoices/{invoice_uuid}/payments"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Lists all invoice payments for a given invoice.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Payments for the invoice are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment`.","example":"subscription_invoice_payment","enum":["subscription_invoice_payment"],"title":"SubscriptionInvoicePaymentType"},"attributes":{"required":["success","amount","gateway"],"properties":{"success":{"type":"boolean","example":true,"description":"Whether the payment was successful."},"pending":{"type":"boolean","example":true,"description":"Whether the payment is pending (only for manual payments)."},"gateway":{"type":"string","maxLength":1024,"example":"elastic_path_payments_stripe","description":"Specifies the payment gateway."},"external_payment_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"failure_detail":{"type":"object","description":"The reason the payment failed.","properties":{"reason":{"type":"string","example":"Card Failure"}},"title":"PaymentFailureDetail"},"amount":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"}},"title":"SubscriptionInvoicePaymentAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps","invoice_id","subscription_id","job_id","manual_payment"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"job_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"payment_taken_at":{"description":"The date and time a payment was taken.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoicePaymentTimestamps"},"manual_payment":{"type":"boolean","example":false,"description":"Whether manual payments are enabled or the payment will be handled by the configured gateway."}},"title":"SubscriptionInvoicePaymentMeta"}},"title":"SubscriptionInvoicePayment"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}}}}
>
  
</StatusCodes>

---

## List subscription invoices

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List subscription invoices"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/invoices"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Lists all invoices for a given subscription.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of invoices is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"description":"This represents the type of resource object being returned. Always `subscription_invoice`.","type":"string","example":"subscription_invoice","enum":["subscription_invoice"],"title":"SubscriptionInvoiceType"},"attributes":{"required":["billing_period","pro_forma","invoice_items","outstanding","tax_required","payment_retries_limit_reached","manual_payment_pending"],"properties":{"billing_period":{"description":"A period of time between a start and end point.","required":["start","end"],"properties":{"start":{"description":"The date and time a billing period started.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"end":{"description":"The date and time a billing period ended.","type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"}},"title":"TimePeriod"},"invoice_items":{"type":"array","items":{"required":["description","price"],"properties":{"description":{"type":"string","description":"A description of the subscribed item.","example":"Magazine issue"},"price":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"from_time_period":{"description":"The start date and time of the billing period in this price","type":"string","example":"2017-01-10T11:41:19.244842Z"},"until_time_period":{"description":"The end date and time of the billing period in this price","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionInvoiceItem"}},"tax_items":{"type":"array","items":{"required":["type","rate"],"properties":{"type":{"description":"This represents the type of resource object being returned. Always `tax_item`.","type":"string","enum":["tax_item"],"example":"tax_item"},"name":{"description":"The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.","type":"string","maxLength":1024,"example":"GST"},"code":{"description":"The unique identifier assigned to goods and services for taxation purposes.","type":"string","maxLength":1024,"example":"20.0 % S"},"rate":{"description":"The tax rate is the percentage of the subscription amount that is required to be paid as tax.","type":"number","format":"double","example":0.2},"jurisdiction":{"description":"The geographic area or political entity that has authority to levy and collect taxes.","type":"string","maxLength":1024,"example":"USA"}},"title":"TaxItem"}},"outstanding":{"type":"boolean","description":"The invoice still requires payment if `true`.","example":true},"number":{"type":"integer","description":"A sequential number assigned by the billing run.","example":1},"tax_required":{"type":"boolean","description":"Whether tax is required for this invoice.","example":true},"payment_retries_limit_reached":{"type":"boolean","description":"Whether the limit of payment retries has been reached.","example":false},"updated_at":{"description":"The date and time an invoice was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time an invoice was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pro_forma":{"description":"Whether the invoice is a Pro Forma invoice (generated ahead of payment) or not.\n\nPro Forma Invoices are created ahead of payment time (for example, a week in advance of payment so\nyou can notify customers) and will not be picked up by a payment run until on or after their valid_from\ndate.\n","type":"boolean","example":false},"valid_from":{"description":"The date and time at which an invoice will be valid from.\n\nIf generated with no lead time then the invoice will be valid immediately.\n\nIf generated with a lead time, then the valid_from will be the data at which the Invoice transitions from\nit's Pro Forma state to one that can have payment taken.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"manual_payment_pending":{"type":"boolean","description":"Whether there is a manual pending payment pending on the invoice.","example":true}},"title":"SubscriptionInvoiceAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","proration_events","pro_rata_remaining_value","display_price"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"subscriber_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"price":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice","description":"Invoice totals formatted for display (`with_tax`, `without_tax`, `tax`). Amounts are in the\ncurrency's smallest subdivision.\n"},"notifications":{"description":"A list of notifications scheduled for this invoice. These are derived from the notification\nschedules configured on the pricing option at the time the invoice was created. Each notification\nhas a due date calculated relative to the billing period end date.\n","type":"array","items":{"description":"A notification scheduled for an invoice.","required":["name","due"],"properties":{"name":{"description":"The name of the notification schedule that generated this notification.","type":"string","example":"7 days before renewal"},"due":{"description":"The date and time when the notification is due to be sent.","type":"string","format":"date-time","example":"2024-01-24T00:00:00Z"},"sent_at":{"description":"The date and time when the notification was sent.","type":"string","format":"date-time","example":"2024-01-24T00:00:00Z"}},"title":"InvoiceNotification"}},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"taxes_added_at":{"description":"The date and time taxes were added to an invoice.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoiceTimestamps"},"proration_events":{"type":"array","items":{"required":["proration_policy_id","billing_cost_before_proration","refunded_amount_for_unused_pricing_option","new_pricing_option_cost","prorated_at"],"properties":{"proration_policy_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"billing_cost_before_proration":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision","example":100},"refunded_amount_for_unused_pricing_option":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"new_pricing_option_cost":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"prorated_at":{"description":"The date and time the subscription was prorated.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"ProrationEvent"}},"pro_rata_remaining_value":{"type":"integer","format":"int64","description":"The pro-rated remaining value for the billing period","example":500}},"title":"SubscriptionInvoiceMeta"}},"title":"SubscriptionInvoice"}},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List subscription plans

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List subscription plans"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/plans"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of plans associated with the specified subscription. Using this endpoint you can see the plan that is currently active in a subscription. If `active_plan` is `true`, a plan is active in a subscription. If `active_plan` is null, the pricing option is not active.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of subscription plans is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List subscription pricing options

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List subscription pricing options"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/pricing-options"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of pricing options associated with the specified subscription. Using this endpoint you can see the pricing options that are currently active in a subscription. If `active_pricing_option` is `true`, a pricing option is active in a subscription. If `active_pricing_option` is null, the pricing option is not active.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of subscription pricing options is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List subscription states

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List subscription states"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/states"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List subscription states

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of subscription states is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_state`.","example":"subscription_state","enum":["subscription_state"],"title":"SubscriptionStateType"},"attributes":{"required":["action"],"properties":{"action":{"type":"string","description":"The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n","example":"cancel","enum":["cancel","pause","resume","pending"],"x-go-type":"model.SubscriptionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"SubscriptionStateAction"},"cancel_immediately":{"type":"boolean","default":false,"example":false,"description":"When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n"}},"title":"SubscriptionStateAttributes"},"meta":{"readOnly":true,"required":["created_at"],"properties":{"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"StateMeta"}},"title":"SubscriptionState"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## List subscriptions

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List subscriptions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v2/subscriptions/subscriptions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all subscriptions.

### Filtering

This endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).

The following attributes and operators are supported.

| Operator | Attribute | Description |
| --- | --- | --- | 
| `eq` | `account_id`, `name`, `email`, `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |
| `in` | `account_id`, `name`, `email`, `external_ref` | In. Checks if the value is in the specified list. If it is, the condition is true. |

### Including Resources

You can use the `include` parameter to include the following resources with this endpoint.

| Resource | Required | Description |
| --- | --- | --- |
| `pricing_options, plans` | Optional | Retrieves all pricing options and plans associated with a subscription. |
| `plans` | Optional | Retrieves all plans associated with a subscription. |
| `pricing_options` | Optional | Retrieves all pricing options associated with a subscription. |

See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"page[offset]","description":"The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"maximum":10000,"example":10}},{"name":"page[limit]","description":"The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":0,"example":100}},{"name":"include","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"array","description":"A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).","example":"plans,pricing_options","items":{"type":"string","enum":["plans","pricing_options"]}}},{"name":"filter","in":"query","required":false,"schema":{"type":"string","format":"string","description":"Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.\n","example":"eq(name,Alan Turing)"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. A list of subscriptions is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription","enum":["subscription"],"title":"SubscriptionType"},"attributes":{"required":["account_id","pricing_option_id","plan_id","offering","currency","name","email"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"address_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"offering":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"},"pricing_option_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"currency":{"type":"string","description":"The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase.","maxLength":1024,"example":"USD","title":"CurrencyIdentifier"},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriptionAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","status","canceled","paused","closed","pending","suspended","invoice_after","manual_payments","first_invoice_prepaid"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"canceled_at":{"description":"The date and time a subscription was cancelled.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"paused_at":{"description":"The date and time a subscription was paused.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"resumed_at":{"description":"The date and time a subscription was resumed.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"end_date":{"description":"The date and time a subscription will end.\n- If the subscription offering pricing option end behavior is `close`, `end_date` is set to the billing period end date upon subscription creation.\n- If the subscription offering pricing option end behavior is \"roll\": `end_date` is set to the billing period end date when the subscription is cancelled.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live_after":{"description":"The date and time a subscription will go live and become active.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live":{"description":"The date and time a subscription was released from the pending state and made active.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"SubscriptionTimestamps"},"status":{"type":"string","description":"The status of a subscription, either `active` or `inactive`.","example":"active","enum":["active","inactive"],"x-go-type":"model.SubscriptionStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"Status"},"state":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_state`.","example":"subscription_state","enum":["subscription_state"],"title":"SubscriptionStateType"},"attributes":{"required":["action"],"properties":{"action":{"type":"string","description":"The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n","example":"cancel","enum":["cancel","pause","resume","pending"],"x-go-type":"model.SubscriptionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"SubscriptionStateAction"},"cancel_immediately":{"type":"boolean","default":false,"example":false,"description":"When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n"}},"title":"SubscriptionStateAttributes"},"meta":{"readOnly":true,"required":["created_at"],"properties":{"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"StateMeta"}},"title":"SubscriptionState"},"manual_payments":{"type":"boolean","example":false,"default":false,"description":"When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments).","title":"ManualPayments"},"first_invoice_prepaid":{"type":"boolean","description":"Indicates that the first billing period of this subscription was paid for outside of the subscriptions service.","example":false},"canceled":{"type":"boolean","description":"Whether a subscription is canceled or not.","example":true},"paused":{"type":"boolean","description":"Whether a subscription is paused or not.","example":true},"closed":{"type":"boolean","description":"Whether a subscription is closed or not.","example":true},"suspended":{"type":"boolean","description":"Whether a subscription is suspended or not.","example":false},"pending":{"type":"boolean","description":"Whether a subscription is pending activation or not.","example":false},"invoice_after":{"description":"The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pending_price_change":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"price_update_history":{"description":"A history of price updates that have been applied to this subscription.","type":"array","x-go-type-skip-optional-pointer":true,"items":{"description":"A record of the previous prices of a subscription before a price change was applied","required":["price_changes","valid_until"],"properties":{"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"valid_until":{"description":"The date and time when the prices were changed (when these previous prices stopped being active)","type":"string","format":"date-time","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionPriceUpdateHistoryEntry"}}},"title":"SubscriptionMeta"}},"title":"Subscription"}},"included":{"readOnly":true,"properties":{"plans":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}},"pricing_options":{"type":"array","items":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}},"title":"SubscriptionIncludes"},"links":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","format":"uri","example":"http://example.com/articles/1/comments","nullable":true,"title":"LinkURI"},{"type":"object","properties":{"href":{"type":"string","format":"uri","example":"http://example.com/articles/1/comments"},"title":{"type":"string","example":"Comments"},"describedby":{"type":"string","format":"uri","example":"http://example.com/schemas/article-comments"}},"title":"LinkObject"}],"title":"Link"},"title":"Links"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Manage subscription plans

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Manage subscription plans"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}/plans"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Manage subscription plans by replacing, changing or detaching plans on the subscription

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"A list of plan IDs to manage on the subscription.","items":{"type":"object","required":["type","plans"],"properties":{"type":{"type":"string","enum":["detach"],"example":"detach","x-go-type":"model.ManagePlansAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"plans":{"type":"array","minItems":1,"items":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}},"title":"ManageSubscriptionPlans"}}},"example":{"data":[{"type":"attach","plans":["bafa601f-359c-48da-834e-377b6c0d9466"]},{"type":"detach","plans":["a8aad94d-60fc-44f7-8dfa-299249566ec4"]}]}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"204":{"description":"Success. The subscription's plans have been updated."},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Offerings

An offering is a combination of plans and pricing options; plans are combined with one or more pricing options to form an offering. 

For example, your company provides online
 streaming of movies, web-series, and music. Your customers can purchase these services through either a weekly or monthly pricing option.

Offering plans can be either:

- a subscription plan, created within an offering.
- a Product Experience Manager product, see [**Create a product**](/docs/api/pxm/products/create-product)

### Offering Examples

Offerings can have any combination of plans and pricing options. The pricing of an offering is determined by the pricing you have configured for your plans and pricing options.

| Example | Plan | Pricing options | Offering |
| --- | --- | --- | --- |
| Single plan and pricing option | One plan with a plan price of $50 | A monthly pricing option with a 5% discount | An offering with a monthly pricing option for $47.50 a month |
| Single plan with multiple pricing options | One plan with a plan price of $50 | A monthly pricing option with a 5% discountA yearly pricing option with a 10% discount | An offering with two pricing options: A monthly pricing option for $47.50 a monthA yearly pricing option for $45 a month |
| Multiple plans and pricing option | Two plans: One plan with a plan price of $50.One plan with a plan price of $75. | A monthly pricing option with a 5% discount. | An offering with a monthly pricing option for $118.75 a month. | 
| Multiple plans with multiple pricing options | Two plans: One plan with a plan price of $50.One plan with a plan price of $75. | A monthly pricing option with a 5% discountA yearly pricing option with a 10% discount | An offering with two pricing options: A monthly pricing option for $118.75 a monthA yearly pricing option for $112.50 a month | 

### Building an Offering

When you are building an offering:

- you can create new pricing options and plans.
- you can modify existing plans and pricing options. For example, you can modify the plan price or any attributes of a pricing option included in the offering.

Here's how you build an offering:

When [**building your offerings**](/docs/api/subscriptions/build-offering) you must supply the plans and pricing options that a customer can choose. An offering can consist of many combinations of a plan or pricing options, depending on the plans and services you offer.

Plans can either be subscription plans or Product Experience Manager products. To create a Product Experience Manager product, see [**Create a product**](/docs/api/pxm/products/create-product)

Pricing options are the rules that govern your subscription, for example, any discount. 
 - You can combine and reuse pricing options for as many plans as you want, making it quick and easy to create your subscription offerings. 
 - An offering must have at least one pricing option.
 - Each plan must have the appropriate pricing option associated with it

When a [**customer**](/docs/api/subscriptions/subscribers) chooses a plan and pricing option, a subscription is created. See [**Subscriptions**](/docs/api/subscriptions/subscriptions). Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription. See [**Invoicing and Billing**](/docs/api/subscriptions/jobs).

### Editing Offerings

After saving an offering, you can, at any time:

- update an offering's details, for example, name or description. See [**Update an Offering**](/docs/api/subscriptions/update-offering).
- update an existing plan in an offering. See [**Update a plan in an offering**](/docs/api/subscriptions/update-offering-plan)
- add a new plan in an offering. See [**Create a plan inside an offering**](/docs/api/subscriptions/create-offering-plan)
- remove plans. See [**Remove a plan from an offering**](/docs/api/subscriptions/delete-offering-plan).
- update an existing pricing option in an offering. See [**Update a pricing option in an offering**](/docs/api/subscriptions/update-offering-pricing-option)
- add a new pricing option to an offering. See [**Create a pricing option inside an offering**](/docs/api/subscriptions/create-offering-pricing-option).
- remove pricing options. See [**Removing a pricing option from an offering**](/docs/api/subscriptions/delete-offering-plan).

Any modifications that you make to offerings, and plans or pricing options in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Proration Policies

Proration is the adjustment of charges or credits on a subscriber's account based on the amount of time a service is used. Proration ensures that subscribers are only charged for the actual time they use the service, whether they upgrade, downgrade, start, or cancel their subscription partway through a billing cycle. This means fair billing for your subscribers and provides you with the flexibility to change your subscribers subscriptions at any time. 

::: note

Subscriptions use client credentials to enable changes to subscriptions, so if you want your shoppers to have the ability to make changes, you can implement a BFF layer using this approach.

:::

Proration occurs for:

- Pricing option upgrades/downgrades:  If a subscriber changes their pricing option in the middle of a billing cycle, proration adjusts the charges to reflect the time spent on each pricing option.
- Service cancellation: If a subscriber cancels a subscription before the end of a billing cycle, they may receive a prorated invoice for the used portion of the subscription.
- Mid-cycle subscription: If a subscriber starts a subscription in the middle of a billing cycle, they are charged a prorated amount for the remaining days in the billing cycle.

There are several scenarios when implementing proration policies.

1. You may want one policy for multiple offerings because only some subscriptions need prorating.
2. You may want a default proration policy for your store.
3. You may want several policies for different offerings. 

In Subscriptions, charges only prorate by day. As soon as a subscriber changes their subscription, a manual billing run is triggered and an invoice is generated with the new price on the next billing run and the difference in price is prorated over days.  

By default, proration is not enabled for Subscriptions. Once you have attached a proration policy to an offering, proration is enabled automatically.

### End dates when switching pricing options

Subscriptions manages the subscription end date when shoppers switch from one pricing option to another. Whether or not an end date is configured depends on the end behavior of the pricing options you are switching between.

| Current Subscription | New Subscription | Proration Behavior | End date |
| --- | --- | --- | --- |
| `close` | `roll` | The subscription switches from a pricing option with a fixed end date to a rolling pricing option so no end date is set after proration. | No end date is configured. |
| `roll` | `close` | The subscription switches to a fixed pricing option, and the end date is configured based on the duration of the pricing option. | An end date is configured. |
| `close` | `close` | The remaining time on the current pricing option is not carried over to the new pricing option. For example, if your current pricing option has 3 months remaining and you switch to a new pricing option that has a fixed length of 6 months, the new end date is calculated as 6 months from the day you switch pricing options, effectively resetting the subscription length to the new pricing option. | New end date calculated from the day you switched pricing option. |

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Removes an offering's pricing options from the plan

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Removes an offering's pricing options from the plan"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}/relationships/pricing_options"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use the unique identifier of the pricing in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"plan_uuid","in":"path","description":"The unique identifier of the plan.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"description":"Enumerates a list of resources that are related.","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}}},"title":"RelationshipsRequest"}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The pricing options are added to the plan","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Schedules

You can schedule your billing, tax, and payment runs. By scheduling billing, tax, and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner.  You can define a schedule in the format (`* * * * *`) which is a set of five fields in a line, indicating when a job should be executed. For example, you can define a schedule so that your job runs multiple times a day, or runs on specific days and months.

Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339). 

### Unrestricted fields

Setting a field to an asterisk (`*`) is sometimes referred to as leaving a field unrestricted because it is not restricted to a specific value.

You can use the asterisk (`*`) to indicate the range of all values for the field. When you use the asterisk, the first value in the range is: 0 for the minute, hour, and day of the week (Sunday) fields, and 1 for day of the month and the month fields.

### Configuring fields

The time fields have the following format and possible values and must be specified in the following order:

| Field | Format | Description  |                                                                                                    
| --- | --- | -----|
| Minute | 0-59 | Indicates how far past the top of the hour your job runs, in minutes. For example if a minute is set to 0, then the job runs at the top of the hour because it is 0 minutes after the hour. This means if the hour is 8.00 AM, the job runs at 8.00 AM. |
| Hour | 0-23 | Indicates how far past midnight your job runs, in hours. This is rounded down to the nearest hours. This is because minutes are indicated by the minute field. |
| Day of the month | 0-31 | Indicates the calendar date of the month. For example, 1 for the first day of the month. |
| Month | 1-12 or JAN to DEC | Indicates the month. Specify the month number or the first three letters of the month name in uppercase. For example, 1 or JAN for January.  |
| Day of the week | 0-6 (or SUN to SAT, or 7 for Sunday) | Indicates the day of the week. Monday is 1, Tuesday is 2, and so on. Either 0 or 7 indicates Sunday. Alternatively, specify the day of the week using the first three letters of the weekday name in uppercase. For example SUN for Sunday. If you use this field with the day of the month field, then this field is evaluated as an inclusive OR. For example, if the day of the month is set to 1 and the day of the week is set to SAT, the job runs on the first day of the month and on every Saturday of the month, even if the first day of the month is not a Saturday. If the day of the week is marked by an asterisk (*) then the field is marked as unrestricted. This means the job only runs on the first day of the month. |

### Matching all values

To match all values for a field, set the field to an asterisk (`*`). When a field is set to an asterisk, the field matches all valid values for that field whenever the other field conditions are satisfied. 

 Here are some examples.

 - `* 0 1 1 1`: the job runs every minute of the midnight hour on January 1st and Mondays.
 - `* * * * *`: the job runs every minute (of every hour, of every day of the month, of every month, every day of the week, because each of these is unrestricted).

 ### Matching a range

 To match a range of values, specify your start and stop values, separated by a hyphen (`-`). Do not include spaces in the range. Ranges are inclusive. The first number must be less than the second number. If you are using abbreviated names for the month or weekday (for example, JAN instead of 1 for the first month of the year), the first value must come earlier in the month or week than the second value.

The following equivalent examples run at midnight on Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays (for all months):

 - `0 0 * * 1-5`
 - `0 0 * * MON-FRI`

### Matching a list

Lists can contain any valid value for the field, including ranges. Specify your values, separated by a comma (,). Do not include spaces in the list.

Examples:

- `0 0,12 * * *`: the job runs at midnight and noon.
- `0-5,30-35 * * * *`: the job runs in each of the first five minutes of every half hour (at the top of the hour and at half past the hour).

### Skipping values in a range

You can skip values in a range by specifying a rate at which to step through the range. To do this, specify the range, followed by the forward slash (`/`) and the rate at which you want to skip through the range.

The step value cannot be larger than the largest possible value for the field. The default step is 1, so the step function `/1` is the same as not using a step function at all.

Example ranges that use step functions:

- `*/2`: this is a valid step function for any field. 
    - For the minute field, it matches 0, 2, 4, ... , 58. 
    - For the hour, it matches 0, 2, 4, ... , 22. 
    - For the day of the month, it matches 1, 3, 5, ... , 31 (for a month with 31 days). 
    - For the month, it matches 1, 3, 5, ... , 11. 
    - For the day of the week, it matches 0, 2, 4, 6.

- `0-12/2`: this is a valid step function for the minute and hour fields. It matches 0, 2, 4, ... , 12.

Example schedules using step functions:

- `*/2 * * * *`: the job runs every two minutes.
- `0 0-12/2 * * *`: the job runs every two hours, on the hour. The first run is at midnight. The last run is at noon.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Subscribers

A subscriber is someone who subscribes to your plan or service.

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Subscriptions Introduction

import ApiLogo from "@theme/ApiLogo";
import Heading from "@theme/Heading";
import SchemaTabs from "@theme/SchemaTabs";
import TabItem from "@theme/TabItem";
import Export from "@theme/ApiExplorer/Export";

<Export
  url={"/assets/openapispecs/subscriptions/public_openapi.yaml"}
  proxy={undefined}
>
  
</Export>

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Subscriptions Introduction"}
>
</Heading>

Elastic Path Subscriptions allows you to offer your customers subscriptions and recurring billing for your plans and services. Elastic Path Subscriptions gives you the flexibility to pause, update, or reactivate your subscription offerings, change subscription cycles and apply discounts.

You can create subscriptions using the Elastic Path Subscriptions API or Commerce Manager See [Subscriptions](/docs/commerce-manager/subscriptions/overview).

Scenarios include:

- repeat products that your customers purchase on a recurring basis.
- membership subscriptions where your customers pay a recurring fee to become members of a particular service, program or organization.
- subscribe and save that allows your customers to subscribe to regular deliveries of products they use frequently, for example, household essentials, or personal care items.

### How Subscriptions Work

Elastic Path Subscriptions enables you to manage your subscriptions plans and pricing options, using offerings. Offerings can contain any combination of plans and pricing options.

Here's how a typical subscription works:

1. Create your offerings. Offerings are the plan and pricing options that a customer can choose. An offering can consist of many combinations of a plan or pricing options, depending on the plans and services you offer. See [**Offerings**](/docs/api/subscriptions/offerings).
2. When a [**customer**](/docs/api/subscriptions/subscribers) chooses a pricing option, a subscription is created. See [**Subscriptions**](/docs/api/subscriptions/subscriptions).
3. Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription. See [**Invoicing and Payments**](/docs/api/subscriptions/invoices).

### Subscriber Management

Elastic Path Subscriptions enables you to create customer accounts that you can use to manage their subscription details, including payment methods and billing information. See [**Subscribers**](/docs/api/subscriptions/subscribers).

### Invoicing & Payments

Elastic Path Subscriptions enables you to manage the billing and recurring payments associated with your customers subscriptions. Elastic Path Subscriptions provides seamless integration with Elastic Path Payments powered by Stripe. See [**Invoicing and Payments**](/docs/api/subscriptions/invoices).

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Bearer Auth"}
      value={"BearerToken"}
    >
      
      
      
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Subscriptions

Elastic Path Subscriptions enables you to manage your subscriptions plans and pricing options, using offerings. Offerings can contain any combination of pricing options and a plan. When a customer chooses a pricing option, a subscription is created.  

### Managing the Subscription Lifecycle

The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan. 

A subscription can have the following states:

- `pending`
- `canceled`
- `paused`
- `resumed`

#### Creating a pending subscription 

A subscription can be created in a `pending` state. This is useful for several reasons.

- If there are subscriptions that require user setup or onboarding, for example, installing software or setting up preferences. This helps reduce shopper frustration during the onboarding process, as the shopper is not paying for a service that they cannot use yet.
- When offering a free trial or promotion, keeping the subscription in a pending state until the trial or promotion starts or ends allows you to manage transitions more smoothly. 
- Before a subscription becomes active, you may need to verify the payment method or authorize the first payment. Keeping the subscription in a pending state allows time to complete these steps without activating the subscription.

For a subscription with a `pending` state, you can also configure a `go_live_after` date. The subscription starts from the `go_live_after` date. This is useful as it ensures both the subscription provider and subscriber are clear about when a subscription officially begins. Once the `go_live_after` date is passed, the subscription becomes `active`, initiating the billing and payment runs. If a subscription is activated this way, you can see this in the `timestamp` meta.   

You can configure a `go_live_after` date to be a past date. This is useful, for example, for backdating a subscription or managing a delay in activating a subscription. Setting the `go_live_after` date in the past ensures the subscriptions timeline correctly aligns with the agreed-upon service start date. 

:::caution

Although, billing runs generate one invoice per subscription, if a `go_live_date` is set far in the past, multiple invoices could be generated over the course of several billing runs, which could be frustrating and confusing to your subscribers. 

:::

See [create a subscription](/docs/api/subscriptions/create-subscription).

#### Cancelling or pausing and resuming subscriptions

A subscriber can decide to cancel or pause and/or resume a subscription. The following example describes pausing or canceling and resuming a subscription.

1. The subscriber pauses or cancels the subscription. 
   - The subscription status is `active`. 
   - either `paused` or `cancelled` is set to `true`.
   - either the `paused_at` or `cancelled_at` timestamp is populated with the date and time the subscription is paused or cancelled.
   - for cancelled subscriptions, `end_date` indicates when the subscription will expire and end.
2. When the next billing run is due, the billing run checks the subscription state. If the subscription state is paused or cancelled then no invoice is created and the subscription status is updated to `inactive`.
3. Subsequent billing runs skip that subscription completely as the subscription status is `inactive`.
4. If the subscriber resumes the subscription:
   - either `paused` or `cancelled` is set to `false`.
   - the `resumed_at` timestamp is populated with the date and time the subscription is resumed.
5. When the next billing run is due, the billing run checks the subscription state. If the `paused` or `cancelled` is set to `false` then the billing run creates an invoice.
6. The payment run processes the invoice. Once the payment succeeds then the payment run updates the status of the subscription to `active`.

### Orders

When a customer chooses a subscription, they need to add the subscription to a cart, checkout the cart and then pay for the order. 

1. When a customer adds a subscription to cart, this is handled using the `Add subscription to cart` endpoint. 
2. Once a subscription has been added to a cart, the [**Checkout API**](/docs/api/carts/checkout-api) converts the cart to an order. 
3. Once the order is created, payment needs to be taken. This is handled by Elastic Path Payments Powered by Stripe. See [**Payments**](/docs/api/subscriptions/invoices#payments).

```mdx-code-block
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

<DocCardList items={useCurrentSidebarCategory().items}/>
```

---

## Update dunning rule policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update dunning rule policy"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/dunning-rules/{dunning_rule_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the rule is not updated. For fields that are optional, an existing value can be removed by specifying a value of null.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"dunning_rule_uuid","in":"path","description":"The unique identifier of a dunning rule set.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_dunning_rule","enum":["subscription_dunning_rule"],"title":"SubscriptionDunningRuleType"},"attributes":{"properties":{"payment_retry_type":{"type":"string","enum":["fixed","backoff","tiered"],"example":"fixed","description":"The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.\n","x-go-type":"model.PaymentRetryType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_interval":{"type":"integer","format":"int64","minimum":1,"maximum":1024,"example":1,"description":"The number of `payment_interval_unit`s to wait between each payment retry attempt.","nullable":true},"payment_retry_unit":{"type":"string","enum":["day","week"],"example":"day","description":"The unit of time used to measure the intervals between payment attempts or retries.","nullable":true,"x-go-type":"model.PaymentRetryUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_multiplier":{"type":"number","format":"double","minimum":1,"maximum":1024,"example":1,"description":"The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types.","nullable":true},"payment_retries_limit":{"type":"integer","format":"int64","minimum":0,"example":5,"description":"The number of times Subscriptions attempts payment retries before `action` is taken."},"action":{"type":"string","enum":["none","pause","close","suspend"],"example":"none","description":"The action to take after all payment attempts for an invoice have failed.","x-go-type":"model.DunningAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"default":{"type":"boolean","example":false,"description":"Set to `true` if you want this rule to be the default for the store."}},"title":"DunningRuleUpdateAttributes"}},"title":"DunningRuleUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The dunning rule set has been updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_dunning_rule","enum":["subscription_dunning_rule"],"title":"SubscriptionDunningRuleType"},"attributes":{"description":"The dunning rule attributes you can use to configure your payment retry strategy.\n","example":{"payment_retry_type":"fixed","payment_retry_unit":"day","payment_retry_interval":1,"payment_retries_limit":10,"action":"none"},"required":["payment_retry_type","payment_retries_limit","action"],"properties":{"payment_retry_type":{"type":"string","enum":["fixed","backoff","tiered"],"example":"fixed","description":"The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.\n","x-go-type":"model.PaymentRetryType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_interval":{"type":"integer","format":"int64","minimum":1,"maximum":1024,"example":1,"description":"The number of `payment_interval_unit`s to wait between each payment retry attempt."},"payment_retry_unit":{"type":"string","enum":["day","week"],"example":"day","description":"The unit of time used to measure the intervals between payment attempts or retries.","x-go-type":"model.PaymentRetryUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"payment_retry_multiplier":{"type":"number","format":"double","minimum":1,"maximum":1024,"example":1,"description":"The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types."},"payment_retries_limit":{"type":"integer","format":"int64","minimum":0,"example":5,"description":"The number of times Subscriptions attempts payment retries before `action` is taken."},"action":{"type":"string","enum":["none","pause","close","suspend"],"example":"none","description":"The action to take after all payment attempts for an invoice have failed.\n\n- None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.\n- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.\n- close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.\n","x-go-type":"model.DunningAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"default":{"type":"boolean","example":false,"description":"Set to `true` if you want this rule to be the default for the store."}},"title":"DunningRuleAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"DunningRuleMeta"}},"title":"DunningRule"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a feature

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a feature"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/features/{feature_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the feature is not updated. For fields that are optional, an existing value can be removed by specifying a value of null.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"feature_uuid","in":"path","description":"The unique identifier of a feature.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_feature","enum":["subscription_feature"],"title":"SubscriptionFeatureType"},"attributes":{"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"nullable":true,"title":"ExternalRefUpdate"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library.","nullable":true},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureUpdateAttributes"}},"title":"FeatureUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The feature details are updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_feature","enum":["subscription_feature"],"title":"SubscriptionFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"Feature"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update Invoice Payment

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Invoice Payment"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/invoices/{invoice_uuid}/payments/{payment_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

External payment methods are payment methods not offered by Elastic Path Subscriptions (such as Elastic Path Payments powered by Stripe or Authorize.net), but they can still be integrated with Subscriptions. You can use the `Update Invoice Payment` endpoint to manually update a payment against an invoice where an external payment method is handling the payment of your invoices. See [External Payments](/docs/api/subscriptions/invoices#external-payments).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"invoice_uuid","in":"path","description":"The unique identifier of the invoice.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"payment_uuid","in":"path","description":"The unique identifier of the payment.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment`.","example":"subscription_invoice_payment","enum":["subscription_invoice_payment"],"title":"SubscriptionInvoicePaymentType"},"attributes":{"required":["success"],"properties":{"success":{"type":"boolean","example":true,"description":"Whether the payment was successful."},"external_payment_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"failure_detail":{"description":"A message generated by an external payment method that describes why a payment fails.","type":"string","example":"Card Failure"},"payment_taken_at":{"description":"The date and time the invoice payment was taken at.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"UpdateInvoicePaymentAttributes"}},"title":"UpdateInvoicePayment"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. Invoice payment has been updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_invoice_payment`.","example":"subscription_invoice_payment","enum":["subscription_invoice_payment"],"title":"SubscriptionInvoicePaymentType"},"attributes":{"required":["success","amount","gateway"],"properties":{"success":{"type":"boolean","example":true,"description":"Whether the payment was successful."},"pending":{"type":"boolean","example":true,"description":"Whether the payment is pending (only for manual payments)."},"gateway":{"type":"string","maxLength":1024,"example":"elastic_path_payments_stripe","description":"Specifies the payment gateway."},"external_payment_id":{"type":"string","maxLength":1024,"example":"33e7ec6b-8b34-4c92-a95b-2e2647922e47","description":"An optional external ID that is specific to the gateway used."},"failure_detail":{"type":"object","description":"The reason the payment failed.","properties":{"reason":{"type":"string","example":"Card Failure"}},"title":"PaymentFailureDetail"},"amount":{"description":"A price in a single currency.","required":["amount","currency"],"properties":{"currency":{"type":"string","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.","example":"USD","maxLength":1024},"amount":{"type":"integer","format":"int64","description":"The value as a whole number of the currency's smallest subdivision.","example":100},"includes_tax":{"type":"boolean","description":"Whether the amount includes any taxes.","example":true}},"example":{"currency":"USD","amount":100,"includes_tax":false},"title":"SingleCurrencyPrice"}},"title":"SubscriptionInvoicePaymentAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps","invoice_id","subscription_id","job_id","manual_payment"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"subscription_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"invoice_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"job_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"payment_taken_at":{"description":"The date and time a payment was taken.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"InvoicePaymentTimestamps"},"manual_payment":{"type":"boolean","example":false,"description":"Whether manual payments are enabled or the payment will be handled by the configured gateway."}},"title":"SubscriptionInvoicePaymentMeta"}},"title":"SubscriptionInvoicePayment"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Updates a feature in an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Updates a feature in an offering"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/features/{feature_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use the unique identifier of the feature in the offering that you want to update. Any modifications that you make to the features in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"feature_uuid","in":"path","description":"The unique identifier of the feature.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_feature","enum":["subscription_offering_feature"],"title":"SubscriptionOfferingFeatureType"},"attributes":{"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"nullable":true,"title":"ExternalRefUpdate"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library.","nullable":true},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureUpdateAttributes"}},"title":"OfferingFeatureUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The feature details are updated on the offering.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_feature","enum":["subscription_feature"],"title":"SubscriptionFeatureType"},"attributes":{"allOf":[{"required":["name","configuration"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"description":{"type":"string","description":"The feature description to display to customers.","maxLength":1024,"example":"Access to over 100 ebooks via the digital library."},"configuration":{"type":"object","required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"oneOf":[{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"required":["type","tag"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureAccessAttributes"},"promotion":{"required":["type","promotions"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"promotions":{"type":"array","items":{"required":["name","tag"],"properties":{"name":{"type":"string","description":"The name of the feature.","minLength":3,"maxLength":1024,"example":"Digital library access"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"promotion_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"FeaturePromotion"}}},"title":"FeaturePromotionAttributes"},"usage":{"required":["type","tag","label","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"},"label":{"type":"string","description":"The property that has a usage limit.","minLength":3,"maxLength":1024,"example":"Digital downloads"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureUsageAttributes"}}},"title":"FeatureConfiguration"}},"title":"FeatureAttributes"}],"title":"FeatureResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"FeatureMeta"}},"title":"Feature"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a plan in an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a plan in an offering"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/plans/{plan_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Use the unique identifier of the plan in the offering that you want to update. Any modifications that you make to the plans in an offering, does not affect any active subscriptions. The changes take effect on all new subscriptions that are created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"plan_uuid","in":"path","description":"The unique identifier of the plan.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"nullable":true,"title":"ExternalRefUpdate"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month.","nullable":true},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1","nullable":true},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg","nullable":true},"price":{"type":"object","additionalProperties":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Whether the amount includes any taxes."}},"nullable":true},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"nullable":true,"title":"NullablePrice"},"price_units":{"type":"object","nullable":true,"description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time, either days or months.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"NullablePriceUnits"}},"title":"PlanUpdateAttributes"},{"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","nullable":true,"oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfigurationUpdate"}}},"title":"OfferingPlanUpdateExtraAttributes"}],"title":"OfferingPlanUpdateAttributes"}},"title":"OfferingPlanUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The plan details are updated on the offering.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_plan","enum":["subscription_offering_plan"],"title":"SubscriptionOfferingPlanType"},"attributes":{"allOf":[{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the plan.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The plan or service description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."},"sku":{"type":"string","description":"A stock keeping unit for the plan, if appropriate.","maxLength":1024,"example":"MAGAZINE1"},"main_image":{"type":"string","format":"uri","description":"A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.","maxLength":1024,"example":"https://magazine.com/cover.jpg"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"price_units":{"type":"object","description":"The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans that all have different prices. Rather than having to create separate pricing options for each plan, you can specify the timeframe during which the plan price is applicable and then create one pricing option that determines the billing frequency for those plans.","required":["unit","amount"],"properties":{"unit":{"type":"string","description":"A unit of time.","enum":["day","month"],"example":"day","x-go-type":"model.PriceUnitsUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","description":"The number of days or months the period covers.","example":7,"minimum":1}},"title":"PriceUnits"}},"title":"PlanAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PlanResponseAttributes"},{"required":["feature_configurations"],"properties":{"feature_configurations":{"type":"object","description":"A map of configurations indicating which features are available for the plan","additionalProperties":{"type":"object","oneOf":[{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}],"discriminator":{"propertyName":"type","mapping":{"access":{"description":"Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.","required":["type"],"properties":{"type":{"type":"string","enum":["access"],"example":"access"}},"title":"FeatureConfigAccessAttributes"},"promotion":{"description":"Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.","required":["type","tag"],"properties":{"type":{"type":"string","enum":["promotion"],"example":"promotion"},"tag":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"title":"FeatureConfigPromotionAttributes"},"usage":{"description":"Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.","required":["type","default_value"],"properties":{"type":{"type":"string","enum":["usage"],"example":"usage"},"default_value":{"type":"integer","description":"The default initial value","example":10}},"title":"FeatureConfigUsageAttributes"}}},"required":["type"],"properties":{"type":{"description":"The type of feature, one of access, promotion or usage.","enum":["access","promotion","usage"],"example":"access","x-go-type":"string"}},"title":"FeaturePlanConfiguration"}}},"title":"OfferingPlanResponseExtraAttributes"}],"title":"OfferingPlanResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"A list of plan prices for each of its pricing options.","additionalProperties":{"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPlanPriceForPricingOption"},"title":"OfferingPlanPrices"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},"active_plan":{"type":"boolean","description":"Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.","example":true,"title":"ActivePlan"}},"title":"PlanMeta"}},"title":"OfferingPlan"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a pricing option in an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a pricing option in an offering"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/offerings/{offering_uuid}/pricing-options/{pricing_option_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a pricing option in an offering

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},{"name":"pricing_option_uuid","in":"path","description":"The unique identifier of the pricing option.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"nullable":true,"title":"ExternalRefUpdate"},"name":{"type":"string","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","example":"A monthly subscription.","maxLength":1024,"nullable":true},"billing_interval_type":{"type":"string","description":"The unit of time in which billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0,"nullable":true},"plan_length":{"type":"integer","description":"The length of time for which a subscription plan is valid. For example, six months after which the plan is renewed.","example":12,"minimum":1},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","nullable":true,"properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"week","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"NullableLeadTime"},"notification_schedule":{"type":"array","items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100,"nullable":true},"fixed_price":{"type":"object","additionalProperties":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Whether the amount includes any taxes."}},"nullable":true},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"nullable":true,"title":"NullablePrice"}},"title":"PricingOptionUpdateAttributes"}},"title":"OfferingPricingOptionUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The pricing option details are updated on the offering.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering_pricing_option","enum":["subscription_offering_pricing_option"],"title":"SubscriptionOfferingPricingOptionType"},"attributes":{"allOf":[{"required":["name","billing_interval_type","billing_frequency","plan_length","end_behavior","can_pause","can_resume","can_cancel"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"A name for the pricing option.","example":"Monthly","minLength":3,"maxLength":1024},"description":{"type":"string","description":"The pricing option description to display to customers.","maxLength":1024,"example":"A monthly subscription."},"billing_interval_type":{"type":"string","description":"The unit of time that billing intervals are measured.","example":"month","enum":["day","week","month","year"],"x-go-type":"model.BillingIntervalType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"billing_frequency":{"type":"integer","description":"The number of intervals between issuing bills.","example":1,"minimum":1},"trial_period":{"type":"integer","description":"The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.","example":7,"minimum":0},"lead_time":{"type":"object","description":"Configuration of the lead time to generate an invoice ahead of time in a pro-forma state","properties":{"type":{"type":"string","description":"The unit of time that lead time is measured in.","example":"day","enum":["day","week"],"x-go-type":"model.LeadTimeType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"time":{"type":"integer","description":"The lead time to generate an invoice ahead of time in a pro-forma state","example":14,"minimum":1}},"required":["type","time"],"title":"LeadTime"},"notification_schedule":{"type":"array","x-go-type-skip-optional-pointer":true,"items":{"type":"object","required":["name","unit","amount"],"properties":{"name":{"type":"string","description":"The name of the schedule.","minLength":1,"maxLength":1024,"example":"Daily billing run."},"unit":{"type":"string","description":"The unit of time that the schedule is measured in.","example":"day","enum":["day","week","month"],"x-go-type":"model.NotificationScheduleUnit","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"amount":{"type":"integer","format":"int64","description":"The number of units between each notification.","example":100,"minimum":1}},"title":"NotificationSchedule"}},"plan_length":{"type":"integer","description":"The number of intervals that the subscription runs for.","example":12,"minimum":1},"end_behavior":{"type":"string","description":"Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.","example":"close","enum":["close","roll"],"x-go-type":"model.EndBehavior","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"can_pause":{"type":"boolean","description":"The subscriber can pause a subscription.","example":false},"can_resume":{"type":"boolean","description":"The subscriber can resume a paused subscription.","example":false},"can_cancel":{"type":"boolean","description":"The subscriber can cancel a subscription.","example":false},"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"PricingOptionResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"prices":{"type":"object","description":"The price of each plan within the offering that this pricing option may be applied to.","readOnly":true,"additionalProperties":{"readOnly":true,"properties":{"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"}},"title":"OfferingPricingOptionPriceForPlan"},"title":"OfferingPricingOptionPrices"},"price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"display_price":{"properties":{"without_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"with_tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting"},"tax":{"required":["amount","currency","formatted"],"properties":{"amount":{"type":"integer","format":"int64","example":100,"description":"The unformatted amount for the objects."},"currency":{"type":"string","format":"string","example":"USD","description":"The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price."},"formatted":{"type":"string","format":"string","example":"$1.00","description":"The formatted amount for the objects."}},"title":"PriceFormatting","description":"Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n"}},"example":{"without_tax":{"amount":100,"currency":"USD","formatted":"$1.00"},"with_tax":{"amount":110,"currency":"USD","formatted":"$1.10"},"tax":{"amount":10,"currency":"USD","formatted":"$0.10"}},"title":"DisplayPrice"},"active_pricing_option":{"type":"boolean","description":"Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.","example":true,"title":"ActivePricingOption"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingPricingOptionMeta"}},"title":"OfferingPricingOption"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update an offering

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an offering"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/offerings/{offering_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

After saving an offering, you can update an offering at any time. Updating an offering does not affect any active subscriptions. The changes take effect on all new subscriptions that are created. For fields that are optional, an existing value can be removed by specifying a value of null.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"offering_uuid","in":"path","description":"The unique identifier of the offering.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"anyOf":[{"required":["attributes"]},{"required":["relationships"]}],"required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"nullable":true,"title":"ExternalRefUpdate"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month.","nullable":true}},"title":"OfferingUpdateAttributes"},"relationships":{"properties":{"proration_policy":{"type":"object","nullable":true,"required":["type","id"],"properties":{"type":{"type":"string","example":"subscription_proration_policy","enum":["subscription_proration_policy"],"title":"ProrationPolicyType"},"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}},"title":"ProrationPolicyUpdateRelationshipAttributes"}},"title":"OfferingUpdateRelationships"}},"title":"OfferingUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The details of the subscription offering are updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update proration policy

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update proration policy"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/proration-policies/{proration_policy_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

You can update a proration policy at any time. For any subscriptions that are using the updated proration policy, the changes are also applied. Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the proration policy is not updated.

When updating proration policies:

- You can change the name of an existing policy.
- You can update `rounding`.
- You can update `external_ref` as long as `external_ref` is still unique in  your store.
- You can remove `external_ref` as this attribute is optional.
- You cannot remove any required attributes, such as `name` or `rounding`.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"proration_policy_uuid","in":"path","description":"The unique identifier of a proration policy.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_proration_policy","enum":["subscription_proration_policy"],"title":"ProrationPolicyType"},"attributes":{"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"nullable":true,"title":"ExternalRefUpdate"},"name":{"type":"string","description":"The name of the proration policy.","minLength":3,"maxLength":1024,"example":"Main Policy"},"rounding":{"type":"string","description":"Whether to round up or down","enum":["up","down","nearest"],"example":"up","x-go-type":"model.ProrationPolicyRounding","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}}},"title":"ProrationPolicyUpdateAttributes"}},"title":"ProrationPolicyUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The proration policy details are updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_proration_policy","enum":["subscription_proration_policy"],"title":"ProrationPolicyType"},"attributes":{"allOf":[{"required":["name","rounding"],"properties":{"name":{"type":"string","description":"A name for the proration policy.","example":"Main Policy","minLength":3,"maxLength":1024},"rounding":{"type":"string","description":"When rounding in proration, you must decide how to round the units of time used to calculate the charges.\n\n- round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use.\n- round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use.\n- round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down.\n","enum":["up","down","nearest"],"example":"up","x-go-type":"model.ProrationPolicyRounding","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"}},"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"}},"title":"ProrationPolicyAttributes"}],"title":"ProrationPolicyResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"ProrationPolicyMeta"}},"title":"ProrationPolicy"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}}}}
>
  
</StatusCodes>

---

## Update a schedule

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a schedule"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/schedules/{schedule_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a schedule

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"schedule_uuid","in":"path","description":"The unique identifier of the schedule.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_schedule","enum":["subscription_schedule"],"title":"SubscriptionScheduleType"},"attributes":{"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"nullable":true,"title":"ExternalRefUpdate"},"name":{"type":"string","description":"The name of the schedule.","minLength":3,"maxLength":1024,"example":"Daily billing run.","nullable":true},"specification":{"type":"string","description":"A cron-style specification of when the jobs should be created.","maxLength":1024,"example":"30 0 * * *"},"location":{"type":"string","description":"The location of the time zone that the schedule operates in.","maxLength":1024,"example":"Europe/London"},"job":{"required":["job_type"],"properties":{"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `payment-run` - a payment run job.\n - `notification-run` - a notification run job.\n","enum":["billing-run","payment-run","notification-run"],"example":"billing-run","x-go-type":"model.JobType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"ScheduleJobType"}},"title":"ScheduleJob"}},"title":"ScheduleUpdateAttributes"}},"title":"ScheduleUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The schedule details are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_schedule","enum":["subscription_schedule"],"title":"SubscriptionScheduleType"},"attributes":{"allOf":[{"required":["specification","location","job"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the schedule.","minLength":3,"maxLength":1024,"example":"Daily billing run."},"specification":{"type":"string","description":"A cron-style specification of when the jobs should be created. See [**Schedules**](/docs/api/subscriptions/schedules).","maxLength":1024,"example":"30 0 * * *"},"location":{"type":"string","description":"The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339).","maxLength":1024,"example":"Europe/London"},"job":{"required":["job_type"],"properties":{"job_type":{"type":"string","description":"The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `payment-run` - a payment run job.\n - `notification-run` - a notification run job.\n","enum":["billing-run","payment-run","notification-run"],"example":"billing-run","x-go-type":"model.JobType","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"ScheduleJobType"}},"title":"ScheduleJob"}},"title":"ScheduleAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"ScheduleResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"scheduled_for":{"type":"string","format":"date-time","example":"2017-07-21T17:32:28Z"},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"ScheduleMeta"}},"title":"Schedule"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a subscriber

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a subscriber"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/subscribers/{subscriber_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a subscriber

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscriber_uuid","in":"path","description":"The unique identifier of the subscriber.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_subscriber","enum":["subscription_subscriber"],"title":"SubscriptionSubscriberType"},"attributes":{"properties":{"name":{"type":"string","description":"The name of the subscriber.","minLength":3,"maxLength":1024,"example":"John Doe"},"email":{"type":"string","format":"email","description":"The email of the subscriber.","minLength":3,"maxLength":1024,"example":"john.doe@example.com","x-go-type":"types.Email","x-go-type-import":{"name":"email","path":"github.com/oapi-codegen/runtime/types"}},"payment_authority":{"type":"object","nullable":true,"oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"NullablePaymentAuthority"}},"title":"SubscriberUpdateAttributes"}},"title":"SubscriberUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The subscriber details are returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_subscriber","enum":["subscription_subscriber"],"title":"SubscriptionSubscriberType"},"attributes":{"allOf":[{"required":["name","email","account_id"],"properties":{"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"name":{"type":"string","description":"The name of the subscriber.","minLength":3,"maxLength":1024,"example":"John Doe"},"email":{"type":"string","format":"email","description":"The email of the subscriber.","minLength":3,"maxLength":1024,"example":"john.doe@example.com","x-go-type":"types.Email","x-go-type-import":{"name":"email","path":"github.com/oapi-codegen/runtime/types"}},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriberAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"SubscriberResponseAttributes"},"meta":{"readOnly":true,"required":["owner","timestamps"],"properties":{"feature_entitlements":{"type":"array","description":"A list of entitlement tags currently active for the subscriber","example":["tag1","tag2"],"items":{"type":"string","description":"A tag to add to the customer's account when entitled to the feature.","minLength":1,"maxLength":64,"pattern":"^[0-9A-Za-z_-]+$","example":"digital_library_access","title":"FeatureTag"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"SubscriberMeta"}},"title":"Subscriber"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"409":{"description":"Write conflict. Unable to perform the operation at this time.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"example":{"errors":[{"title":"Write Conflict","status":"409"}]}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Update a subscription

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";
import Translate from "@docusaurus/Translate";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a subscription"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v2/subscriptions/subscriptions/{subscription_uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates a subscription. For example, a subscriber can switch from one pricing option to another in a subscription.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  parameters={[{"name":"subscription_uuid","in":"path","description":"The unique identifier of the subscription.","required":true,"schema":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription","enum":["subscription"],"title":"SubscriptionType"},"attributes":{"properties":{"pricing_option_id":{"type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000001"},"plan_id":{"type":"string","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000001"},"address_id":{"type":"string","format":"UUID","nullable":true,"x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"00000000-0000-0000-0000-000000000001"},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"},"go_live_after":{"description":"The date and time a `pending` subscription goes live and becomes active. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription).","type":"string","example":"2017-01-10T11:41:19.244842Z","nullable":true}},"title":"SubscriptionUpdateAttributes"}},"title":"SubscriptionUpdate"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Success. The subscription is updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription","enum":["subscription"],"title":"SubscriptionType"},"attributes":{"required":["account_id","pricing_option_id","plan_id","offering","currency","name","email"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"account_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"address_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"offering":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","example":"subscription_offering","enum":["subscription_offering"],"title":"SubscriptionOfferingType"},"attributes":{"allOf":[{"required":["name"],"properties":{"external_ref":{"description":"A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.","type":"string","example":"abc123","maxLength":2048,"title":"ExternalRef"},"name":{"type":"string","description":"The name of the offering.","minLength":3,"maxLength":1024,"example":"Magazine"},"description":{"type":"string","description":"The offering description to display to customers.","maxLength":1024,"example":"A lovely magazine that is published every month."}},"title":"OfferingAttributes"},{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}],"title":"OfferingResponseAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","external_plan_refs"],"properties":{"external_plan_refs":{"type":"array","items":{"readOnly":true,"type":"string","format":"string","description":"The offerings plan external_ref value","example":"97dddc65-eabd-45d8-b45b-2ece5cfc8c50","title":"OfferingPlanExternalRefMeta"}},"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"}},"title":"OfferingMeta"}},"title":"Offering"},"pricing_option_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"plan_id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"currency":{"type":"string","description":"The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase.","maxLength":1024,"example":"USD","title":"CurrencyIdentifier"},"payment_authority":{"type":"object","oneOf":[{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}],"discriminator":{"propertyName":"type","mapping":{"elastic_path_payments_stripe":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["elastic_path_payments_stripe"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityEPPayments"},"stripe_payment_intents":{"writeOnly":true,"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"stripe_payment_intents","enum":["stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"customer_id":{"description":"The unique identifier for a customer.","type":"string","minLength":3,"maxLength":1024,"example":"cus_OPfKlxWV3hp9h6"},"card_id":{"description":"The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).","type":"string","minLength":3,"maxLength":1024,"example":"card_8Diw3FQPhxK27WADPVMeXieP"}},"title":"PaymentAuthorityStripe"},"authorize_net":{"type":"object","required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"authorize_net","enum":["authorize_net"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}},"payment_profile_id":{"description":"The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511660856"},"customer_profile_id":{"description":"The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.","type":"string","minLength":3,"maxLength":1024,"example":"1511736979"}},"title":"PaymentAuthorityAuthorizeNet"}}},"required":["type"],"properties":{"type":{"description":"The name of the payment gateway facilitating the secure transmission of payment data.","type":"string","example":"elastic_path_payments_stripe","enum":["authorize_net","elastic_path_payments_stripe","stripe_payment_intents"],"x-go-type":"paymentgateways.GatewayName","x-go-type-import":{"name":"paymentgateways","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways"}}},"title":"PaymentAuthority"}},"title":"SubscriptionAttributes"},"relationships":{"description":"Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.","additionalProperties":{"anyOf":[{"description":"The subscription resource that is related.","properties":{"data":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"SingleRelationship"},{"description":"The list of resources that are related.","properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource being returned.","example":"11111111-2222-3333-4444-555555555555"}},"title":"RelationshipData"}},"links":{"description":"Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren’t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to check for these special cases. \n\n - current - Always the current page.\n - first - Always the first page.\n - last - always `null`.\n - next - `null` if the user is on the first page.\n - previous - `null` if there is only one page.\n","type":"object","properties":{"related":{"type":"string","example":"foo.bar"}},"title":"RelationshipLinks"}},"title":"ManyRelationship"}],"title":"Relationship"},"example":{"pricing-options":{"links":{"related":"/offerings/:offering-id/pricing-options","self":"/offerings/:offering-id"},"data":{"type":"offering-pricing-option","id":"625fe958-7b4b-40a0-a2c0-dbb8f31eec0d"}}},"title":"Relationships"},"meta":{"readOnly":true,"required":["owner","timestamps","status","canceled","paused","closed","pending","suspended","invoice_after","manual_payments","first_invoice_prepaid"],"properties":{"owner":{"readOnly":true,"type":"string","format":"string","description":"The owner of a resource, either `store` or `organization`.","example":"store","title":"OwnerMeta"},"timestamps":{"allOf":[{"required":["created_at","updated_at"],"properties":{"updated_at":{"description":"The date and time a resource was updated.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"Timestamps"},{"properties":{"canceled_at":{"description":"The date and time a subscription was cancelled.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"paused_at":{"description":"The date and time a subscription was paused.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"resumed_at":{"description":"The date and time a subscription was resumed.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"end_date":{"description":"The date and time a subscription will end.\n- If the subscription offering pricing option end behavior is `close`, `end_date` is set to the billing period end date upon subscription creation.\n- If the subscription offering pricing option end behavior is \"roll\": `end_date` is set to the billing period end date when the subscription is cancelled.\n","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live_after":{"description":"The date and time a subscription will go live and become active.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"go_live":{"description":"The date and time a subscription was released from the pending state and made active.","type":"string","example":"2017-01-10T11:41:19.244842Z"}}}],"title":"SubscriptionTimestamps"},"status":{"type":"string","description":"The status of a subscription, either `active` or `inactive`.","example":"active","enum":["active","inactive"],"x-go-type":"model.SubscriptionStatus","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"Status"},"state":{"required":["type","attributes","meta"],"properties":{"id":{"type":"string","description":"The unique identifier.","format":"uuid","x-go-type":"uuid.UUID","x-go-type-import":{"name":"uuid","path":"github.com/google/uuid"},"example":"11111111-2222-3333-4444-555555555555","title":"UUID"},"type":{"type":"string","description":"This represents the type of resource object being returned. Always `subscription_state`.","example":"subscription_state","enum":["subscription_state"],"title":"SubscriptionStateType"},"attributes":{"required":["action"],"properties":{"action":{"type":"string","description":"The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#managing-the-subscription-lifecycle).\n","example":"cancel","enum":["cancel","pause","resume","pending"],"x-go-type":"model.SubscriptionAction","x-go-type-import":{"name":"model","path":"gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model"},"title":"SubscriptionStateAction"},"cancel_immediately":{"type":"boolean","default":false,"example":false,"description":"When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n"}},"title":"SubscriptionStateAttributes"},"meta":{"readOnly":true,"required":["created_at"],"properties":{"created_at":{"description":"The date and time a resource was created.","type":"string","example":"2017-01-10T11:41:19.244842Z"}},"title":"StateMeta"}},"title":"SubscriptionState"},"manual_payments":{"type":"boolean","example":false,"default":false,"description":"When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments).","title":"ManualPayments"},"first_invoice_prepaid":{"type":"boolean","description":"Indicates that the first billing period of this subscription was paid for outside of the subscriptions service.","example":false},"canceled":{"type":"boolean","description":"Whether a subscription is canceled or not.","example":true},"paused":{"type":"boolean","description":"Whether a subscription is paused or not.","example":true},"closed":{"type":"boolean","description":"Whether a subscription is closed or not.","example":true},"suspended":{"type":"boolean","description":"Whether a subscription is suspended or not.","example":false},"pending":{"type":"boolean","description":"Whether a subscription is pending activation or not.","example":false},"invoice_after":{"description":"The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.","type":"string","example":"2017-01-10T11:41:19.244842Z"},"pending_price_change":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"price_update_history":{"description":"A history of price updates that have been applied to this subscription.","type":"array","x-go-type-skip-optional-pointer":true,"items":{"description":"A record of the previous prices of a subscription before a price change was applied","required":["price_changes","valid_until"],"properties":{"price_changes":{"properties":{"plan_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"},"example":{"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}},"pricing_option_prices":{"x-go-type-skip-optional-pointer":true,"additionalProperties":{"properties":{"base_price_percentage":{"type":"number","format":"double","description":"A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.","example":90,"minimum":0,"maximum":100},"fixed_price":{"additionalProperties":{"type":"object","description":"The base price.","required":["amount"],"properties":{"amount":{"type":"integer","format":"int64","minimum":0,"example":100,"description":"The value as a whole number of the currency's smallest subdivision."},"includes_tax":{"type":"boolean","example":true,"description":"Indicates whether the amount includes any taxes."}}},"example":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}},"title":"Price"}},"title":"PricingOptionPrice"},"example":{"83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c":{"base_price_percentage":90},"197a11f4-d341-4594-9574-7fbfbe6a671d":{"USD":{"amount":100,"includes_tax":false},"GBP":{"amount":90,"includes_tax":true}}}}},"title":"SubscriptionPriceChanges"},"valid_until":{"description":"The date and time when the prices were changed (when these previous prices stopped being active)","type":"string","format":"date-time","example":"2017-01-10T11:41:19.244842Z"}},"title":"SubscriptionPriceUpdateHistoryEntry"}}},"title":"SubscriptionMeta"}},"title":"Subscription"}}}}}},"400":{"description":"Bad request. The request failed validation.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"missing-name":{"value":{"errors":[{"title":"Validation Error","status":"400","detail":"data.attributes.name: \"name\" is required"}]}}}}}},"403":{"description":"Forbidden. The operation is forbidden on this entity.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Permission denied","status":"404","detail":"Permission denied: plan tenancy mismatch"}]}}}}}},"404":{"description":"Not found. The requested entity does not exist.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"not-found":{"value":{"errors":[{"title":"Not Found","status":"404","detail":"No plan found"}]}}}}}},"500":{"description":"Internal server error. There was a system failure in the platform.","content":{"application/json":{"schema":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"required":["status","title"],"properties":{"status":{"type":"string","description":"The HTTP response code of the error.","example":"500"},"title":{"type":"string","description":"A brief summary of the error.","example":"Internal server error"},"detail":{"type":"string","description":"Optional additional detail about the error.","example":"An internal error has occurred."},"meta":{"type":"object","description":"Additional supporting meta data for the error.","example":{"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}}},"title":"Error"}}},"title":"ErrorResponse"},"examples":{"internal-server-error":{"value":{"errors":[{"title":"Internal Server Error","status":"500"}]}}}}}}}}
>
  
</StatusCodes>

---

## Security

Store administrators and team members share responsibility for keeping a store secure.

## User Credentials

Store admins receive their user credentials from Elastic Path to log in to Composable Commerce. Store admins can invite team members to work on a store.

After a team member receives an invitation to a Composable Commerce store, they register and create their username and password. Store admins do not have access to the user credentials of the team members.

:::caution
Never share your user credentials.
:::

## API Authentication Credentials

All API requests must contain a generated access token for authentication purposes. To generate an access token, you need your API keys. API keys are the client ID and client secret. Access tokens expire after a predefined period of time. Application keys are used to manage your stores directly. They are not associated to a specific user, and are identified based on their names.

:::caution
Never share your API keys or generated access tokens.
:::

You can generate different types of access tokens based on the level of access needed for a particular task.

- `client_credentials` token - Enables full access to all resources in the store. Use this type of token to create, read, update, or delete resources by using the API.
- `implicit` token - Enables read access to resources in the store. Use this type of token to perform actions that a store customer would do, that is, access live resources available from the storefront.

In addition, an `account` or `customer` token is required to access a shopper profile, including addresses and order history when using an `implicit` token.

:::caution
Removing a team member removes the unique ClientID and Client Secret associated with that team member.
:::

## Single Sign-on

Single sign-on allows authentication with Commerce using an external authentication provider. Using an existing authentication provider allows for integration with company-specific or customizable authentication systems. In some cases, it can also simplify the log-in experience because they don’t need to remember another password. For more information, see [Single Sign-on](/docs/api/single-sign-on).

## Related Resources

- [Your first API request](/guides/Getting-Started/your-first-api-request)
- [Authentication](/docs/api/authentication)
- [Application Keys](/docs/api/application-keys/application-keys-introduction)

---

## Get Customer Authentication Settings

## `GET` Get Customer Authentication Settings

```http
https://useast.api.elasticpath.com/v2/settings/customer-authentication
```

## Parameters

### Headers

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Examples

### Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/settings/customer-authentication \
     -H "Authorization: Bearer XXXX" \
```

### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
});
Moltin.AuthenticationSettings.Get().then((authenticationSettings) => {
    // Do something
});
// Where `EPCC` is an authenticated client
await EPCC.AuthenticationSettingsEndpoint.Get();
```

## Response Example

`200 OK`

```json
{
    "data": {
        "id": "88888888-4444-4333-8333-111111111111",
        "meta": {
            "client_id": "customers"
        },
        "relationships": {
            "authentication-realm": {
                "data": {
                    "id": "40086652-2779-45f0-8ea6-ae630dfd13cb",
                    "links": {
                        "self": "https://useast.api.elasticpath.com/v2/authentication-realms/40086652-2779-45f0-8ea6-ae630dfd13cb"
                    },
                    "duplicate_email_policy": "allowed",
                    "type": "authentication-realm"
                }
            }
        },
        "type": "customer-authentication-settings"
    }
}
```

---

## Customer Authentication Settings

You can use the Customer Authentication Settings endpoint to retrieve settings controlling customer authentication.

## The Customer Authentication Settings object

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | The unique identifier for these customer authentication settings. |
| `meta` | `object` | Additional information for these customer authentication settings. Also see: [The meta object](#the-meta-object) below. |
| `relationships` | `object` | Related resources. Also see: [The relationships object](#the-relationships-object) below. |
| `type` | `string` | The type represents the object being returned. |

## Sample Object

```json
{
    "data": {
        "id": "88888888-4444-4333-8333-111111111111",
        "meta": {
            "client_id": "customers"
        },
        "relationships": {
            "authentication-realm": {
                "data": {
                    "id": "40086652-2779-45f0-8ea6-ae630dfd13cb",
                    "links": {
                        "self": "https://useast.api.elasticpath.com/v2/authentication-realms/40086652-2779-45f0-8ea6-ae630dfd13cb"
                    },
                    "duplicate_email_policy": "allowed",
                    "type": "authentication-realm"
                }
            }
        },
        "type": "customer-authentication-settings"
    }
}
```

## The `meta` object

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `meta.client_id` | `string` | The client id to be used in Single Sign On authentication flows for customers. For more information on where to use this client id, refer to the Developer How-To: [Single sign-on with OpenID Connect](/guides/How-To/Authentication/get-single-sign-on-account-management-token). |

## The `relationships` object

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `relationships.authentication-realm` | `object` | Relationship information regarding the authentication realm entity used for authentication for this store. |
| `relationships.authentication-realm.data` | `object` | Information regarding the authentication realm entity. |
| `relationships.authentication-realm.data.id` | `string` | The id of the authentication realm entity. |
| `relationships.authentication-realm.data.type` | `string` | The type of the authentication realm entity. |

---

## Permissions

Permissions are managed through tokens. There are two authentication methods, `client_credentials` and `implicit`. See [Client credentials vs Implicit](/docs/api/authentication/authentication#client-credentials-vs-implicit-use-case-scenarios) for the difference.

[Account management authentication token](/docs/api/authentication/authentication#account-authentication) combined with an `implicit` access token is used to manage user interfaces that involve restricted account related data. This data may include orders, addresses, and account details.

[Customer token](/docs/api/authentication/authentication#customer-authentication) combined with an `implicit` access token is used to manage user interfaces that involve restricted customer related data. This data may include orders, addresses, and customer details.

## Breakdown of Access (for shoppers)

The following tables show a breakdown of the API endpoint actions that are available to the implicit token.

### Implicit

 | Endpoint                                     | Read access | Write access |
 |----------------------------------------------| --- | --- |
 | `/accounts`                                  | ⛔️ | ⛔️ |
 | `/account-members`                           | ⛔️ | ⛔️ |
 | `/account-membership`                        | ⛔️ | ⛔️ |
 | `/application-keys`                          | ⛔️ | ⛔️ |
 | `/authentication-realms`                     | ✅ | ⛔️ |
 | `/brands`                                    | ✅ | ⛔️ |
 | `/carts`                                     | ✅ | ✅ |
 | `/categories`                                | ✅ | ⛔️ |
 | `/checkout`                                  | ✅ | ✅ |
 | `/collections`                               | ✅ | ⛔️ |
 | `/currencies`                                | ✅ | ⛔️ |
 | `/customers`                                 | ⛔️ | ⛔️ |
 | `/files`                                     | ✅ | ⛔️ |
 | `/flows`                                     | ✅ | ⛔️ |
 | `/gateways`                                  | ⛔️ | ⛔️ |
 | `/integrations`                              | ⛔️ | ⛔️ |
 | `/inventories`                               | ✅ | ⛔️ |
 | `/jobs`                                      | ⛔️ | ⛔️ |
 | `/pcm/jobs`                                  | ⛔️ | ⛔️ |
 | `/merchant-realm-mappings`                   | ⛔️ | ⛔️ |
 | `/orders`                                    | ⛔️ | ⛔️ |
 | `/orders/:id`                                | ⛔️ | ⛔️ |
 | `/v2/products`                               | ✅ | ⛔️ |
 | `/catalog/products`                          | ✅ | ⛔️ |
 | `/catalog/hierarchies`                       | ✅ | ⛔️ |
 | `/catalog/nodes`                             | ✅ | ⛔️ |
 | `/pcm/products`                              | ⛔️ | ⛔️ |
 | `/pcm/hierarchies`                           | ⛔️ | ⛔️ |
 | `/pcm/pricebooks`                            | ⛔️ | ⛔️ |
 | `/pcm/catalogs`                              | ⛔️ | ⛔️ |
 | `/permissions`                               | ⛔️ | ⛔️ |
 | `/promotions`                                | ⛔️ | ⛔️ |
 | `/settings`                                  | ⛔️ | ⛔️ |
 | `/settings/account-authentication`  | ⛔️ | ⛔️ |
 | `/settings/customer-authentication` | ⛔️ | ⛔️ |
 | `/settings/extensions`                       | ⛔️ | ⛔️ |
 | `/variations`                                | ⛔️ | ⛔️ |

### Implicit + Account Management Authentication Token

| Endpoint                                     | Read access | Write access |
|----------------------------------------------|-------------|--------------|
| `/accounts`                                  | ✅️          | ⛔️           |
| `/account-members`                           | ✅️          | ⛔️           |
| `/account-membership`                        | ✅           | ⛔️           |
| `/application-keys`                          | ⛔️          | ⛔️           |
| `/authentication-realms`                     | ✅           | ⛔️           |
| `/brands`                                    | ✅           | ⛔️           |
| `/carts`                                     | ✅           | ✅            |
| `/categories`                                | ✅           | ⛔️           |
| `/checkout`                                  | ✅           | ✅            |
| `/collections`                               | ✅           | ⛔️           |
| `/currencies`                                | ✅           | ⛔️           |
| `/customers`                                 | ⛔           | ⛔            |
| `/files`                                     | ✅           | ⛔️           |
| `/flows`                                     | ✅           | ⛔️           |
| `/gateways`                                  | ⛔️          | ⛔️           |
| `/integrations`                              | ⛔️          | ⛔️           |
| `/inventories`                               | ✅           | ⛔️           |
| `/jobs`                                      | ⛔️          | ⛔️           |
| `/pcm/jobs`                                  | ⛔️          | ⛔️           |
| `/merchant-realm-mappings`                   | ⛔️          | ⛔️           |
| `/orders`                                    | ✅           | ⛔️           |
| `/orders/:id`                                | ✅           | ⛔️           |
| `/v2/products`                               | ✅           | ⛔️           |
| `/catalog/products`                          | ✅           | ⛔️           |
| `/catalog/hierarchies`                       | ✅           | ⛔️           |
| `/catalog/nodes`                             | ✅           | ⛔️           |
| `/pcm/products`                              | ⛔️          | ⛔️           |
| `/pcm/hierarchies`                           | ⛔️          | ⛔️           |
| `/pcm/pricebooks`                            | ⛔️          | ⛔️           |
| `/pcm/catalogs`                              | ⛔️          | ⛔️           |
| `/permissions`                               | ⛔️          | ⛔️           |
| `/promotions`                                | ⛔️          | ⛔️           |
| `/settings`                                  | ⛔️          | ⛔️           |
| `/settings/account-authentication`  | ⛔️          | ⛔️           |
| `/settings/customer-authentication` | ⛔️          | ⛔️           |
| `/settings/extensions`                       | ⛔️          | ⛔️           |
| `/variations`                                | ⛔️          | ⛔️           |

Note that you can only fetch data with live status.

### Implicit + Customer Token

| Endpoint                                     | Read access | Write access |
 |----------------------------------------------|-------------|--------------|
| `/accounts`                                  | ⛔️          | ⛔️           |
| `/account-members`                           | ⛔️          | ⛔️           |
| `/account-membership`                        | ⛔️          | ⛔️           |
| `/application-keys`                          | ⛔️          | ⛔️           |
| `/authentication-realms`                     | ✅           | ⛔️           |
| `/brands`                                    | ✅           | ⛔️           |
| `/carts`                                     | ✅           | ✅            |
| `/categories`                                | ✅           | ⛔️           |
| `/checkout`                                  | ✅           | ✅            |
| `/collections`                               | ✅           | ⛔️           |
| `/currencies`                                | ✅           | ⛔️           |
| `/customers`                                 | ✅           | ✅            |
| `/files`                                     | ✅           | ⛔️           |
| `/flows`                                     | ✅           | ⛔️           |
| `/gateways`                                  | ⛔️          | ⛔️           |
| `/integrations`                              | ⛔️          | ⛔️           |
| `/inventories`                               | ✅           | ⛔️           |
| `/jobs`                                      | ⛔️          | ⛔️           |
| `/pcm/jobs`                                  | ⛔️          | ⛔️           |
| `/merchant-realm-mappings`                   | ⛔️          | ⛔️           |
| `/orders`                                    | ✅           | ⛔️           |
| `/orders/:id`                                | ✅           | ⛔️           |
| `/v2/products`                               | ✅           | ⛔️           |
| `/catalog/products`                          | ✅           | ⛔️           |
| `/catalog/hierarchies`                       | ✅           | ⛔️           |
| `/catalog/nodes`                             | ✅           | ⛔️           |
| `/pcm/products`                              | ⛔️          | ⛔️           |
| `/pcm/hierarchies`                           | ⛔️          | ⛔️           |
| `/pcm/pricebooks`                            | ⛔️          | ⛔️           |
| `/pcm/catalogs`                              | ⛔️          | ⛔️           |
| `/permissions`                               | ⛔️          | ⛔️           |
| `/promotions`                                | ⛔️          | ⛔️           |
| `/settings`                                  | ⛔️          | ⛔️           |
| `/settings/account-authentication`  | ⛔️          | ⛔️           |
| `/settings/customer-authentication` | ⛔️          | ⛔️           |
| `/settings/extensions`                       | ⛔️          | ⛔️           |
| `/variations`                                | ⛔️          | ⛔️           |

## Breakdown of Access (for sellers)

The following tables show a breakdown of the API endpoint actions that are available to the client credentials token for each role. Refer to the [Team Management](/guides/Getting-Started/team-management) page for a comparison of different roles.

### Seller admin

| Endpoint                                     | Read access | Write access |
|----------------------------------------------|-------------|--------------|
| `/accounts`                                  | ✅           | ✅            |
| `/account-members`                           | ✅           | ✅            |
| `/account-membership`                        | ✅           | ✅            |
| `/application-keys`                          | ✅           | ✅            |
| `/authentication-realms`                     | ✅           | ✅            |
| `/brands`                                    | ✅           | ✅            |
| `/carts`                                     | ✅           | ✅            |
| `/categories`                                | ✅           | ✅            |
| `/checkout`                                  | ✅           | ✅            |
| `/collections`                               | ✅           | ✅            |
| `/currencies`                                | ✅           | ✅            |
| `/customers`                                 | ✅           | ✅            |
| `/files`                                     | ✅           | ✅            |
| `/flows`                                     | ✅           | ✅            |
| `/gateways`                                  | ✅           | ✅            |
| `/integrations`                              | ✅           | ✅            |
| `/inventories`                               | ✅           | ✅            |
| `/jobs`                                      | ✅           | ✅            |
| `/pcm/jobs`                                  | ✅           | ✅            |
| `/personal-data/logs`                        | ✅           | ✅            |
| `/personal-data/personal-data-entries`       | ✅           | ✅            |
| `/merchant-realm-mappings`                   | ✅           | ✅            |
| `/orders`                                    | ✅           | ✅            |
| `/orders/:id`                                | ✅           | ✅            |
| `/v2/products`                               | ✅           | ✅            |
| `/catalog/products`                          | ✅           | ✅            |
| `/catalog/hierarchies`                       | ✅           | ✅            |
| `/catalog/nodes`                             | ✅           | ✅            |
| `/pcm/products`                              | ✅           | ✅            |
| `/pcm/hierarchies`                           | ✅           | ✅            |
| `/pcm/pricebooks`                            | ✅           | ✅            |
| `/pcm/catalogs`                              | ✅           | ✅            |
| `/permissions`                               | ✅           | ✅            |
| `/promotions`                                | ✅           | ✅            |
| `/settings`                                  | ✅           | ✅            |
| `/settings/account-authentication`  | ✅ ️         | ⛔            |
| `/settings/customer-authentication` | ✅           | ⛔            |
| `/settings/extensions`                       | ✅           | ✅            |
| `/subscriptions`                             | ✅           | ✅            |
| `/user-roles`                                | ✅           | ✅            |
| `/variations`                                | ✅           | ✅            |

### Basic user

| Endpoint                               | Read access | Write access |
|----------------------------------------| --- | --- |
| `/accounts`                            | ✅️ | ✅️ |
| `/account-members`                     | ⛔️ | ⛔️ |
| `/account-membership`                  | ⛔️ | ⛔️ |
| `/application-keys`                    | ⛔️ | ⛔️ |
| `/authentication-realms`               | ⛔️ | ⛔️ |
| `/brands`                              | ⛔️ | ⛔️ |
| `/carts`                               | ⛔️ | ⛔️ |
| `/categories`                          | ⛔️ | ⛔️ |
| `/checkout`                            | ⛔️ | ⛔️ |
| `/collections`                         | ⛔️ | ⛔️ |
| `/currencies`                          | ✅️ | ⛔️ |
| `/customers`                           | ✅️ | ✅️ |
| `/files`                               | ⛔️ | ⛔️ |
| `/flows`                               | ✅️ | ⛔️ |
| `/gateways`                            | ⛔️ | ⛔️ |
| `/integrations`                        | ⛔️ | ⛔️ |
| `/inventories`                         | ✅ | ⛔️ |
| `/jobs`                                | ⛔️ | ⛔️ |
| `/pcm/jobs`                            | ⛔️ | ⛔️ |
| `/personal-data/logs`                  | ⛔️ | ⛔️ |
| `/personal-data/personal-data-entries` | ⛔️ | ⛔️ |
| `/merchant-realm-mappings`             | ⛔️ | ⛔️ |
| `/orders`                              | ⛔️ | ⛔️ |
| `/orders/:id`                          | ⛔️ | ⛔️ |
| `/v2/products`                         | ⛔️ | ⛔️ |
| `/catalog/products`                    | ⛔️ | ⛔️ |
| `/catalog/hierarchies`                 | ⛔️ | ⛔️ |
| `/catalog/nodes`                       | ⛔️ | ⛔️ |
| `/pcm/products`                        | ⛔️ | ⛔️ |
| `/pcm/hierarchies`                     | ⛔️ | ⛔️ |
| `/pcm/pricebooks`                      | ⛔️ | ⛔️ |
| `/pcm/catalogs`                        | ⛔️ | ⛔️ |
| `/permissions`                         | ⛔️ | ⛔️ |
| `/promotions`                          | ⛔️ | ⛔️ |
| `/settings`                            | ⛔️ | ⛔️ |
| `/settings/account-authentication`  | ⛔️ | ⛔️ |
| `/settings/customer-authentication` | ⛔️ | ⛔️ |
| `/settings/extensions`                 | ⛔️ | ⛔️ |
| `/subscriptions      `                 | ⛔️ | ⛔️ |
| `/user-roles`                          | ✅ | ⛔️ |
| `/variations`                          | ⛔️ | ⛔️ |

### Marketing/Sales

| Endpoint                               | Read access | Write access |
|----------------------------------------| --- | --- |
| `/accounts`                            | ⛔️ | ⛔️ |
| `/account-members`                     | ⛔️ | ⛔️ |
| `/account-membership`                  | ⛔️ | ⛔️ |
| `/application-keys`                    | ⛔️ | ⛔️ |
| `/authentication-realms`               | ⛔ | ⛔ |
| `/brands`                              | ✅ | ✅ |
| `/carts`                               | ⛔ | ⛔ |
| `/categories`                          | ✅ | ✅ |
| `/checkout`                            | ⛔ | ⛔ |
| `/collections`                         | ✅ | ✅ |
| `/currencies`                          | ✅ | ⛔ |
| `/customers`                           | ⛔ | ⛔ |
| `/files`                               | ✅ | ✅ |
| `/flows`                               | ✅ | ✅ |
| `/gateways`                            | ⛔️ | ⛔️ |
| `/integrations`                        | ⛔ | ⛔ |
| `/inventories`                         | ✅ | ✅ |
| `/jobs`                                | ⛔ | ⛔ |
| `/pcm/jobs`                            | ✅ | ✅ |
| `/personal-data/logs`                  | ⛔️ | ⛔️ |
| `/personal-data/personal-data-entries` | ⛔️ | ⛔️ |
| `/merchant-realm-mappings`             | ⛔ | ⛔ |
| `/orders`                              | ⛔ | ⛔ |
| `/orders/:id`                          | ⛔ | ⛔ |
| `/v2/products`                         | ✅ | ✅ |
| `/catalog/products`                    | ✅ | ⛔️ |
| `/catalog/hierarchies`                 | ✅ | ⛔️ |
| `/catalog/nodes`                       | ✅ | ⛔️ |
| `/pcm/products`                        | ✅ | ✅ |
| `/pcm/hierarchies`                     | ✅ | ✅ |
| `/pcm/pricebooks`                      | ✅ | ✅ |
| `/pcm/catalogs`                        | ✅ | ✅ |
| `/permissions`                         | ⛔️ | ⛔️ |
| `/promotions`                          | ✅ | ✅ |
| `/settings`                            | ⛔ | ⛔ |
| `/settings/account-authentication`  | ⛔️ | ⛔️ |
| `/settings/customer-authentication` | ⛔️ | ⛔️ |
| `/settings/extensions`                 | ⛔️ | ⛔️ |
| `/subscriptions`                       | ⛔️ | ⛔️ |
| `/user-roles`                          | ✅ | ⛔ |
| `/variations`                          | ✅ | ✅ |

### Support

| Endpoint                               | Read access | Write access |
|----------------------------------------| --- | --- |
| `/accounts`                            | ✅️ | ✅️ |
| `/account-members`                     | ✅️ | ✅️ |
| `/account-membership`                  | ✅️ | ✅️ |
| `/application-keys`                    | ⛔️ | ⛔️ |
| `/authentication-realms`               | ⛔️ | ⛔️ |
| `/brands`                              | ⛔️ | ⛔️ |
| `/carts`                               | ⛔️ | ⛔️ |
| `/categories`                          | ⛔️ | ⛔️ |
| `/checkout`                            | ⛔️ | ⛔️ |
| `/collections`                         | ⛔️ | ⛔️ |
| `/currencies`                          | ✅️ | ⛔️ |
| `/customers`                           | ✅️ | ✅️ |
| `/files`                               | ⛔️ | ⛔️ |
| `/flows`                               | ✅️ | ⛔️ |
| `/gateways`                            | ⛔️ | ⛔️ |
| `/integrations`                        | ⛔️ | ⛔️ |
| `/inventories`                         | ⛔️ | ⛔️ |
| `/jobs`                                | ⛔️ | ⛔️ |
| `/pcm/jobs`                            | ⛔️ | ⛔️ |
| `/personal-data/logs`                  | ✅ | ✅️ |
| `/personal-data/personal-data-entries` | ✅ | ✅️ |
| `/merchant-realm-mappings`             | ⛔️ | ⛔️ |
| `/orders`                              | ✅ | ✅️ |
| `/orders/:id`                          | ✅ | ✅️ |
| `/v2/products`                         | ⛔️ | ⛔️ |
| `/catalog/products`                    | ⛔️ | ⛔️ |
| `/catalog/hierarchies`                 | ⛔️ | ⛔️ |
| `/catalog/nodes`                       | ⛔️ | ⛔️ |
| `/pcm/products`                        | ⛔️ | ⛔️ |
| `/pcm/hierarchies`                     | ⛔️ | ⛔️ |
| `/pcm/pricebooks`                      | ⛔️ | ⛔️ |
| `/pcm/catalogs`                        | ⛔️ | ⛔️ |
| `/permissions`                         | ⛔️ | ⛔️ |
| `/promotions`                          | ⛔️ | ⛔️ |
| `/settings`                            | ⛔️ | ⛔️ |
| `/settings/account-authentication`  | ✅️ | ⛔️ |
| `/settings/customer-authentication` | ✅️ | ⛔️ |
| `/settings/extensions`                 | ⛔️ | ⛔️ |
| `/subscriptions`                       | ⛔️ | ⛔️ |
| `/user-roles`                          | ✅ | ⛔️ |
| `/variations`                          | ⛔️ | ⛔️ |

### IT/Developer

| Endpoint                               | Read access | Write access |
|----------------------------------------| --- | --- |
| `/accounts`                            | ⛔️ | ⛔️ |
| `/account-members`                     | ⛔️ | ⛔️ |
| `/account-membership`                  | ⛔️ | ⛔️ |
| `/application-keys`                    | ✅ | ✅ |
| `/authentication-realms`               | ✅️ | ✅ |
| `/brands`                              | ⛔️ | ⛔️ |
| `/carts`                               | ⛔️ | ⛔️ |
| `/categories`                          | ⛔️ | ⛔️ |
| `/checkout`                            | ⛔️ | ⛔️ |
| `/collections`                         | ⛔️ | ⛔️ |
| `/currencies`                          | ✅️ | ✅️ |
| `/customers`                           | ⛔️ | ⛔️ |
| `/files`                               | ⛔️ | ⛔️ |
| `/flows`                               | ✅️ | ✅️ |
| `/gateways`                            | ✅️️ | ✅️️ |
| `/integrations`                        | ✅️ | ✅️ |
| `/inventories`                         | ⛔️ | ⛔️ |
| `/jobs`                                | ⛔️ | ⛔️ |
| `/pcm/jobs`                            | ⛔️ | ⛔️ |
| `/personal-data/logs`                  | ✅ | ✅️ |
| `/personal-data/personal-data-entries` | ✅ | ✅️ |
| `/merchant-realm-mappings`             | ✅ | ✅️ |
| `/orders`                              | ⛔️ | ⛔️ |
| `/orders/:id`                          | ⛔️ | ⛔️ |
| `/v2/products`                         | ⛔️ | ⛔️ |
| `/catalog/products`                    | ⛔️ | ⛔️ |
| `/catalog/hierarchies`                 | ⛔️ | ⛔️ |
| `/catalog/nodes`                       | ⛔️ | ⛔️ |
| `/pcm/products`                        | ⛔️ | ⛔️ |
| `/pcm/hierarchies`                     | ⛔️ | ⛔️ |
| `/pcm/pricebooks`                      | ⛔️ | ⛔️ |
| `/pcm/catalogs`                        | ⛔️ | ⛔️ |
| `/permissions`                         | ✅ | ✅️ |
| `/promotions`                          | ⛔️ | ⛔️ |
| `/settings`                            | ⛔️ | ⛔️ |
| `/settings/account-authentication`  | ✅️ | ⛔ |
| `/settings/customer-authentication` | ✅️ | ⛔ |
| `/settings/extensions`                 | ✅ | ✅️ |
| `/subscriptions`                       | ✅ | ✅️ |
| `/user-roles`                          | ✅ | ✅️ |
| `/variations`                          | ⛔️ | ⛔️ |

### Promotions Manager

| Endpoint                                     | Read access | Write access |
|----------------------------------------------| --- | --- |
| `/accounts`                                  | ⛔️ | ⛔️ |
| `/account-members`                           | ⛔️ | ⛔️ |
| `/account-membership`                        | ⛔️ | ⛔️ |
| `/application-keys`                          | ⛔️ | ⛔️ |
| `/authentication-realms`                     | ⛔ | ⛔ |
| `/brands`                                    | ⛔ | ⛔ |
| `/carts`                                     | ⛔ | ⛔ |
| `/categories`                                | ⛔ | ⛔ |
| `/checkout`                                  | ⛔ | ⛔ |
| `/collections`                               | ⛔ | ⛔ |
| `/currencies`                                | ✅ | ⛔ |
| `/customers`                                 | ⛔ | ⛔ |
| `/files`                                     | ⛔️ | ⛔ |
| `/flows`                                     | ✅ | ⛔ |
| `/gateways`                                  | ⛔️ | ⛔️ |
| `/integrations`                              | ⛔ | ⛔ |
| `/inventories`                               | ⛔ | ⛔ |
| `/jobs`                                      | ⛔ | ⛔ |
| `/pcm/jobs`                                  | ⛔ | ⛔ |
| `/personal-data/logs`                        | ⛔️ | ⛔️ |
| `/personal-data/personal-data-entries`       | ⛔️ | ⛔️ |
| `/merchant-realm-mappings`                   | ⛔ | ⛔ |
| `/orders`                                    | ⛔ | ⛔ |
| `/orders/:id`                                | ⛔ | ⛔ |
| `/v2/products`                               | ⛔ | ⛔ |
| `/catalog/products`                          | ⛔ | ⛔️ |
| `/catalog/hierarchies`                       | ⛔ | ⛔️ |
| `/catalog/nodes`                             | ⛔ | ⛔️ |
| `/pcm/products`                              | ✅ | ⛔ |
| `/pcm/hierarchies`                           | ✅ | ⛔ |
| `/pcm/pricebooks`                            | ⛔ | ⛔ |
| `/pcm/catalogs`                              | ✅ | ⛔ |
| `/permissions`                               | ⛔️ | ⛔️ |
| `/promotions`                                | ✅ | ✅ |
| `/settings`                                  | ⛔ | ⛔ |
| `/settings/account-authentication`  | ⛔️ | ⛔️ |
| `/settings/customer-authentication` | ⛔️ | ⛔️ |
| `/settings/extensions`                       | ⛔️ | ⛔️ |
| `/subscriptions`                             | ⛔️ | ⛔️ |
| `/user-roles`                                | ✅ | ⛔ |
| `/variations`                                | ⛔ | ⛔ |

### eCommerce Admin

| Endpoint                               | Read access | Write access |
|----------------------------------------| --- | --- |
| `/accounts`                            | ✅ | ✅ |
| `/account-members`                     | ✅ | ✅ |
| `/account-membership`                  | ✅ | ✅ |
| `/application-keys`                    | ⛔️ | ⛔️ |
| `/authentication-realms`               | ⛔ | ⛔ |
| `/brands`                              | ✅ | ✅ |
| `/carts`                               | ⛔ | ⛔ |
| `/categories`                          | ✅ | ✅ |
| `/checkout`                            | ⛔ | ⛔ |
| `/collections`                         | ✅ | ✅ |
| `/currencies`                          | ✅ | ⛔ |
| `/customers`                           | ✅ | ✅ |
| `/files`                               | ✅ | ✅ |
| `/flows`                               | ✅ | ✅ |
| `/gateways`                            | ⛔️ | ⛔️ |
| `/integrations`                        | ⛔ | ⛔ |
| `/inventories`                         | ✅ | ✅ |
| `/jobs`                                | ⛔ | ⛔ |
| `/pcm/jobs`                            | ✅ | ✅ |
| `/personal-data/logs`                  | ✅ | ✅ |
| `/personal-data/personal-data-entries` |✅ | ✅ |
| `/merchant-realm-mappings`             | ⛔ | ⛔ |
| `/orders`                              | ✅ | ✅ |
| `/orders/:id`                          | ✅ | ✅ |
| `/v2/products`                         | ✅ | ✅ |
| `/catalog/products`                    | ✅ | ⛔️ |
| `/catalog/hierarchies`                 | ✅ | ⛔️ |
| `/catalog/nodes`                       | ✅ | ⛔️ |
| `/pcm/products`                        | ✅ | ✅ |
| `/pcm/hierarchies`                     | ✅ | ✅ |
| `/pcm/pricebooks`                      | ✅ | ✅ |
| `/pcm/catalogs`                        | ✅ | ✅ |
| `/permissions`                         | ⛔️ | ⛔️ |
| `/promotions`                          | ✅ | ✅ |
| `/settings`                            | ⛔ | ⛔ |
| `/settings/account-authentication`  | ✅ | ⛔️ |
| `/settings/customer-authentication` | ✅ | ⛔️ |
| `/settings/extensions`                  | ⛔️ | ⛔️ |
| `/subscriptions     `                  | ⛔️ | ⛔️ |
| `/user-roles`                          | ✅ | ⛔ |
| `/variations`                          | ✅ | ✅ |

## Related Resources

- [Team Management](/guides/Getting-Started/team-management)

---

## Includes

You can use `include=promotions` to retrieve condensed promotion from the following endpoints:

- [Get a Cart](/docs/api/carts/get-a-cart)
- [Get Cart Items](/docs/api/carts/get-cart-items)
- [Get an Order](/docs/api/carts/get-an-order)
- [Get Order Items](/docs/api/carts/get-order-items)

See [Condensed promotions](/docs/api/promotions/promotions-standard-introduction#condensed-promotion).

When a promotion is deleted, the discount associated with it becomes inactive. If the promotion is deleted but still remains in the cart, it does not appear in the `included` section of the response body.

## `GET` Retrieve Promotions from a Cart

```http
https://useast.api.elasticpath.com/v2/carts/:id?include=promotions
```

## Parameters

### Path parameters

| Name        | Required | Type     | Description                              |
|:------------|:---------|:---------|:-----------------------------------------|
| `id` | Required | `string` | The unique identifier of the cart that you created. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Query parameters

| Name      | Required | Type     | Description                                |
|:----------|:---------|:---------|:-------------------------------------------|
| `include` | Optional | `string` | The promotions for a cart. |

## Request Example - Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/carts/:id?include=promotions \
     -H "Authorization: Bearer XXXX"
```

## Response Example

The following response example shows condensed promotions for cart discounts within the included object. 

When you create a cart discount rule promotion, an item discount rule promotion and a standard cart discount promotion, and apply these discounts to a cart with eligible items, then upon calling `GET {{baseUrl}}/carts/{{cartID}}?include=promotions` endpoint, the cart relationship object has the promotion item. Additionally, the `included` object contains condensed promotions for the cart discounts.

`200 OK`

```json
{
    "data": {
        "id": "1",
        "type": "cart",
        "name": "my cart name",
        "description": "cart description",
        "discount_settings": {
            "custom_discounts_enabled": false,
            "use_rule_promotions": true
        },
        "links": {
            "self": "https://useast.api.elasticpath.com/v2/carts/1"
        },
        "meta": {
            "display_price": {
                "with_tax": {
                    "amount": 6000,
                    "currency": "USD",
                    "formatted": "$60.00"
                },
                "without_tax": {
                    "amount": 6000,
                    "currency": "USD",
                    "formatted": "$60.00"
                },
                "tax": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "discount": {
                    "amount": -4000,
                    "currency": "USD",
                    "formatted": "-$40.00"
                },
                "without_discount": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                },
                "shipping": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2024-05-24T17:38:10Z",
                "updated_at": "2024-05-31T16:26:07Z",
                "expires_at": "2024-06-07T16:26:07Z"
            }
        },
        "relationships": {
            "items": {
                "data": [
                    {
                        "type": "promotion_item",
                        "id": "0bf2c5d6-0930-48c3-86da-f0ae6fcb0ad7"
                    },
                    {
                        "type": "cart_item",
                        "id": "1a317de0-5375-4175-8a0d-7ecea776fb89"
                    },
                    {
                        "type": "promotion_item",
                        "id": "1fec2974-3578-4b7d-bd7e-2ed626cbec2c"
                    }
                ]
            },
            "customers": {},
            "accounts": {},
            "promotions": {
                "data": [
                    {
                        "type": "promotion",
                        "id": "e4d929d5-f471-4317-9a86-a84a6c572b44"
                    },
                    {
                        "type": "promotion",
                        "id": "05b35539-7946-4145-a8ff-bfd3cefc7691"
                    }
                ]
            }
        }
    },
    "included": {
        "promotions": [
            {
                "type": "promotion",
                "id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
                "name": "cart20",
                "description": "cart20",
                "automatic": false,
                "promotion_source": "rule-promotion",
                "start": "2024-04-01T18:24:06Z",
                "end": "2024-06-01T18:24:09Z"
            },
            {
                "type": "promotion",
                "id": "05b35539-7946-4145-a8ff-bfd3cefc7691",
                "name": "v1cart10",
                "description": "v1cart10",
                "automatic": false,
                "promotion_type": "fixed_discount",
                "start": "2024-04-01T17:25:00Z",
                "end": "2024-06-01T17:25:03Z"
            }
        ]
    }
}
```

## GET Retrieve Promotions from Cart Items

```http
https://useast.api.elasticpath.com/v2/carts/:id/items?include=promotions`
```

## Parameters

### Path parameters

| Name        | Required | Type     | Description                              |
|:------------|:---------|:---------|:-----------------------------------------|
| `id` | Required | `string` | The unique identifier of the cart that you created. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Query parameters

| Name      | Required | Type     | Description                                |
|:----------|:---------|:---------|:-------------------------------------------|
| `include` | Optional | `string` | The promotions for cart items. |

## Request Example - Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/carts/:id/items?include=promotions \
     -H "Authorization: Bearer XXXX"
```

## Response Example

The following response example shows condensed promotion for both cart discount and item discounts.

`200 OK`

```json
{
    "data": [
        {
            "id": "1a317de0-5375-4175-8a0d-7ecea776fb89",
            "type": "cart_item",
            "product_id": "5a4662d2-9a2b-4f6e-a215-2970db914b0c",
            "name": "sku1",
            "description": "sku1",
            "sku": "sku1",
            "slug": "sku1",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "discounts": [
                {
                    "amount": {
                        "amount": -1000,
                        "currency": "USD",
                        "includes_tax": false
                    },
                    "code": "sale2024",
                    "id": "de19a043-a6da-4bde-b896-d17e16b77e25",
                    "promotion_source": "rule-promotion"
                },
                {
                    "amount": {
                        "amount": -2000,
                        "currency": "USD",
                        "includes_tax": false
                    },
                    "code": "sale2024",
                    "id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
                    "promotion_source": "rule-promotion",
                    "is_cart_discount": true
                }
            ],
            "links": {
                "product": "https://useast.api.elasticpath.com/v2/products/5a4662d2-9a2b-4f6e-a215-2970db914b0c"
            },
            "relationships": {
                "taxes": {
                    "data": null
                },
                "custom_discounts": {
                    "data": null
                },
                "promotions": {
                    "data": [
                        {
                            "type": "promotion",
                            "id": "de19a043-a6da-4bde-b896-d17e16b77e25"
                        },
                        {
                            "type": "promotion",
                            "id": "e4d929d5-f471-4317-9a86-a84a6c572b44"
                        }
                    ]
                }
            },
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 6000,
                            "currency": "USD",
                            "formatted": "$60.00"
                        },
                        "value": {
                            "amount": 6000,
                            "currency": "USD",
                            "formatted": "$60.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 6000,
                            "currency": "USD",
                            "formatted": "$60.00"
                        },
                        "value": {
                            "amount": 6000,
                            "currency": "USD",
                            "formatted": "$60.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": -4000,
                            "currency": "USD",
                            "formatted": "-$40.00"
                        },
                        "value": {
                            "amount": -4000,
                            "currency": "USD",
                            "formatted": "-$40.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    },
                    "discounts": {
                        "sale2024": {
                            "amount": -3000,
                            "currency": "USD",
                            "formatted": "-$30.00",
                            "constituents": {
                                "de19a043-a6da-4bde-b896-d17e16b77e25": {
                                    "amount": -1000,
                                    "currency": "USD",
                                    "formatted": "-$10.00"
                                },
                                "e4d929d5-f471-4317-9a86-a84a6c572b44": {
                                    "amount": -2000,
                                    "currency": "USD",
                                    "formatted": "-$20.00"
                                }
                            }
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-05-31T16:26:04Z",
                    "updated_at": "2024-05-31T16:26:04Z"
                }
            },
            "catalog_id": "09b9359f-897f-407f-89a2-702e167fe781",
            "catalog_source": "pim"
        },
        {
            "id": "0bf2c5d6-0930-48c3-86da-f0ae6fcb0ad7",
            "type": "promotion_item",
            "promotion_id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
            "name": "cart20",
            "description": "Promotion",
            "sku": "sale2024",
            "slug": "",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": -2000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": -2000,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {},
            "relationships": {
                "taxes": {
                    "data": null
                },
                "custom_discounts": {
                    "data": null
                },
                "promotions": {
                    "data": [
                        {
                            "type": "promotion",
                            "id": "e4d929d5-f471-4317-9a86-a84a6c572b44"
                        }
                    ]
                }
            },
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        },
                        "value": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        },
                        "value": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "",
                            "formatted": "0"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "",
                            "formatted": "0"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-05-31T16:26:07Z",
                    "updated_at": "2024-05-31T16:26:07Z"
                }
            },
            "promotion_source": "rule-promotion"
        },
        {
            "id": "1fec2974-3578-4b7d-bd7e-2ed626cbec2c",
            "type": "promotion_item",
            "promotion_id": "05b35539-7946-4145-a8ff-bfd3cefc7691",
            "name": "v1cart10",
            "description": "Promotion",
            "sku": "sale2024",
            "slug": "",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {},
            "relationships": {
                "taxes": {
                    "data": null
                },
                "custom_discounts": {
                    "data": null
                },
                "promotions": {
                    "data": [
                        {
                            "type": "promotion",
                            "id": "05b35539-7946-4145-a8ff-bfd3cefc7691"
                        }
                    ]
                }
            },
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "value": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "value": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "",
                            "formatted": "0"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "",
                            "formatted": "0"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-05-31T16:26:07Z",
                    "updated_at": "2024-05-31T16:26:07Z"
                }
            }
        }
    ],
    "meta": {
        "display_price": {
            "with_tax": {
                "amount": 6000,
                "currency": "USD",
                "formatted": "$60.00"
            },
            "without_tax": {
                "amount": 6000,
                "currency": "USD",
                "formatted": "$60.00"
            },
            "tax": {
                "amount": 0,
                "currency": "USD",
                "formatted": "$0.00"
            },
            "discount": {
                "amount": -4000,
                "currency": "USD",
                "formatted": "-$40.00"
            },
            "without_discount": {
                "amount": 10000,
                "currency": "USD",
                "formatted": "$100.00"
            },
            "shipping": {
                "amount": 0,
                "currency": "USD",
                "formatted": "$0.00"
            }
        },
        "timestamps": {
            "created_at": "2024-05-24T17:38:10Z",
            "updated_at": "2024-05-31T16:26:07Z",
            "expires_at": "2024-06-07T16:26:07Z"
        }
    },
    "included": {
        "promotions": [
            {
                "type": "promotion",
                "id": "05b35539-7946-4145-a8ff-bfd3cefc7691",
                "name": "v1cart10",
                "description": "v1cart10",
                "automatic": false,
                "promotion_type": "fixed_discount",
                "start": "2024-04-01T17:25:00Z",
                "end": "2024-06-01T17:25:03Z"
            },
            {
                "type": "promotion",
                "id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
                "name": "cart20",
                "description": "cart20",
                "automatic": false,
                "promotion_source": "rule-promotion",
                "start": "2024-04-01T18:24:06Z",
                "end": "2024-06-01T18:24:09Z"
            },
            {
                "type": "promotion",
                "id": "de19a043-a6da-4bde-b896-d17e16b77e25",
                "name": "item10",
                "description": "item10",
                "automatic": false,
                "promotion_source": "rule-promotion",
                "start": "2024-05-02T04:28:24Z",
                "end": "2024-06-02T04:28:28Z"
            }
        ]
    }
}
```

## `GET` Retrieve Promotions from an order

```http
https://useast.api.elasticpath.com/v2/orders/:id?include=promotions`
```

## Parameters

### Path parameters

| Name | Required | Type     | Description          |
|:-----|:---------|:---------|:---------------------|
| `id` | Required | `string` | The ID of the order. |

### Query parameters 

| Name | Required | Type     | Description          |
|:-----|:---------|:---------|:---------------------|
| `include` | Required | `string` | The promotions included for the order. |

## Request Example -Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/orders/:id?include=promotions \
     -H "Authorization: Bearer XXXX"
```

## Response Example

`200 OK`

```json
{
    "data": {
        "id": "522dd525-38cb-4d25-9903-9d417b568096",
        "type": "order",
        "web_order_id": null,
        "status": "incomplete",
        "payment": "unpaid",
        "shipping": "unfulfilled",
        "anonymized": false,
        "customer": {
            "name": "kevin",
            "email": "andy@example.com"
        },
        "shipping_address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "phone_number": "123-456-1111",
            "company_name": "Elasticpath",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "city": "Sunny Town",
            "postcode": "v1v 1v1",
            "county": "BC",
            "country": "CA",
            "instructions": ""
        },
        "billing_address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "company_name": "Elasticpath",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "city": "Sunny Town",
            "postcode": "v1v 1v1",
            "county": "BC",
            "country": "CA"
        },
        "links": {},
        "meta": {
            "display_price": {
                "with_tax": {
                    "amount": 6000,
                    "currency": "USD",
                    "formatted": "$60.00"
                },
                "without_tax": {
                    "amount": 6000,
                    "currency": "USD",
                    "formatted": "$60.00"
                },
                "tax": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "discount": {
                    "amount": -4000,
                    "currency": "USD",
                    "formatted": "-$40.00"
                },
                "balance_owing": {
                    "amount": 6000,
                    "currency": "USD",
                    "formatted": "$60.00"
                },
                "paid": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "authorized": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "without_discount": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                },
                "shipping": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2024-05-31T16:43:31Z",
                "updated_at": "2024-05-31T16:43:31Z"
            }
        },
        "relationships": {
            "items": {
                "data": [
                    {
                        "type": "item",
                        "id": "874aa011-c160-4819-8a87-7b54be25481b"
                    },
                    {
                        "type": "item",
                        "id": "baf6e9f6-f248-477c-b508-3788957908cf"
                    },
                    {
                        "type": "item",
                        "id": "58e6c654-fe32-4bdf-ae88-958c988fb1b3"
                    }
                ]
            },
            "promotions": {
                "data": [
                    {
                        "type": "promotion",
                        "id": "05b35539-7946-4145-a8ff-bfd3cefc7691"
                    },
                    {
                        "type": "promotion",
                        "id": "e4d929d5-f471-4317-9a86-a84a6c572b44"
                    }
                ]
            }
        }
    },
    "included": {
        "promotions": [
            {
                "type": "promotion",
                "id": "05b35539-7946-4145-a8ff-bfd3cefc7691",
                "name": "v1cart10",
                "description": "v1cart10",
                "automatic": false,
                "promotion_type": "fixed_discount",
                "start": "2024-04-01T17:25:00Z",
                "end": "2024-06-01T17:25:03Z"
            },
            {
                "type": "promotion",
                "id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
                "name": "cart20",
                "description": "cart20",
                "automatic": false,
                "promotion_source": "rule-promotion",
                "start": "2024-04-01T18:24:06Z",
                "end": "2024-06-01T18:24:09Z"
            }
        ]
    }
}
```

## `GET` Retrieve Promotions from order items

```http
https://useast.api.elasticpath.com/v2/orders/:id/items
```

## Parameters

### Path parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | Required | `string` | The ID of the order. |

### Headers

| Name | Required | Type | Description                                             |
| --- | --- | --- |---------------------------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API.     |
| `X-Moltin-Customer-Token` | Optional | `string` | A customer token to access a specific customer's order. |

### Query parameters

| Name      | Required | Type     | Description                                |
|:----------|:---------|:---------|:-------------------------------------------|
| `include` | Optional | `string` | The promotions for order items. |

## Request Example - Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/orders/:id/items?include=promotions  \
     -H "Authorization: Bearer XXXX"
```

## Response Example

The following response example shows `included` object containing both order-level and item-level promotions.

`200 OK`

```json
{
    "data": [
        {
            "id": "874aa011-c160-4819-8a87-7b54be25481b",
            "type": "order_item",
            "custom_field_test": null,
            "tracking_number": null,
            "quantity": 1,
            "product_id": "05b35539-7946-4145-a8ff-bfd3cefc7691",
            "name": "v1cart10",
            "sku": "sale2024",
            "unit_price": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {},
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "value": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "value": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "value": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-05-31T16:43:31Z",
                    "updated_at": "2024-05-31T16:43:31Z"
                }
            },
            "relationships": {
                "cart_item": {
                    "data": {
                        "type": "cart_item",
                        "id": "6d55f4b1-2869-4b31-a214-0cbe11ac6722"
                    }
                },
                "promotions": {
                    "data": [
                        {
                            "type": "promotion",
                            "id": "05b35539-7946-4145-a8ff-bfd3cefc7691"
                        }
                    ]
                }
            }
        },
        {
            "id": "baf6e9f6-f248-477c-b508-3788957908cf",
            "type": "promotion_item",
            "custom_field_test": null,
            "tracking_number": null,
            "quantity": 1,
            "product_id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
            "name": "cart20",
            "sku": "sale2024",
            "unit_price": {
                "amount": -2000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": -2000,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {},
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        },
                        "value": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        },
                        "value": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        },
                        "value": {
                            "amount": -2000,
                            "currency": "USD",
                            "formatted": "-$20.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-05-31T16:43:31Z",
                    "updated_at": "2024-05-31T16:43:31Z"
                }
            },
            "relationships": {
                "cart_item": {
                    "data": {
                        "type": "cart_item",
                        "id": "614d4801-5077-468d-9514-db81306d1560"
                    }
                },
                "promotions": {
                    "data": [
                        {
                            "type": "promotion",
                            "id": "e4d929d5-f471-4317-9a86-a84a6c572b44"
                        }
                    ]
                }
            },
            "promotion_source": "rule-promotion"
        },
        {
            "id": "58e6c654-fe32-4bdf-ae88-958c988fb1b3",
            "type": "order_item",
            "custom_field_test": null,
            "tracking_number": null,
            "quantity": 1,
            "product_id": "5a4662d2-9a2b-4f6e-a215-2970db914b0c",
            "name": "sku1",
            "sku": "sku1",
            "unit_price": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "discounts": [
                {
                    "amount": {
                        "amount": -2000,
                        "currency": "USD",
                        "includes_tax": false
                    },
                    "code": "sale2024",
                    "id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
                    "promotion_source": "rule-promotion",
                    "is_cart_discount": true
                },
                {
                    "amount": {
                        "amount": -1000,
                        "currency": "USD",
                        "includes_tax": false
                    },
                    "code": "sale2024",
                    "id": "de19a043-a6da-4bde-b896-d17e16b77e25",
                    "promotion_source": "rule-promotion"
                }
            ],
            "links": {},
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 6000,
                            "currency": "USD",
                            "formatted": "$60.00"
                        },
                        "value": {
                            "amount": 6000,
                            "currency": "USD",
                            "formatted": "$60.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 6000,
                            "currency": "USD",
                            "formatted": "$60.00"
                        },
                        "value": {
                            "amount": 6000,
                            "currency": "USD",
                            "formatted": "$60.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": -4000,
                            "currency": "USD",
                            "formatted": "-$40.00"
                        },
                        "value": {
                            "amount": -4000,
                            "currency": "USD",
                            "formatted": "-$40.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    },
                    "discounts": {
                        "sale2024": {
                            "amount": -3000,
                            "currency": "USD",
                            "formatted": "-$30.00",
                            "constituents": {
                                "de19a043-a6da-4bde-b896-d17e16b77e25": {
                                    "amount": -1000,
                                    "currency": "USD",
                                    "formatted": "-$10.00"
                                },
                                "e4d929d5-f471-4317-9a86-a84a6c572b44": {
                                    "amount": -2000,
                                    "currency": "USD",
                                    "formatted": "-$20.00"
                                }
                            }
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-05-31T16:43:31Z",
                    "updated_at": "2024-05-31T16:43:31Z"
                }
            },
            "relationships": {
                "cart_item": {
                    "data": {
                        "type": "cart_item",
                        "id": "2745400a-39f5-4b7b-ae77-c84b2ca1a723"
                    }
                },
                "promotions": {
                    "data": [
                        {
                            "type": "promotion",
                            "id": "e4d929d5-f471-4317-9a86-a84a6c572b44"
                        },
                        {
                            "type": "promotion",
                            "id": "de19a043-a6da-4bde-b896-d17e16b77e25"
                        }
                    ]
                }
            },
            "catalog_id": "09b9359f-897f-407f-89a2-702e167fe781",
            "catalog_source": "pim"
        }
    ],
    "included": {
        "promotions": [
            {
                "type": "promotion",
                "id": "05b35539-7946-4145-a8ff-bfd3cefc7691",
                "name": "v1cart10",
                "description": "v1cart10",
                "automatic": false,
                "promotion_type": "fixed_discount",
                "start": "2024-04-01T17:25:00Z",
                "end": "2024-06-01T17:25:03Z"
            },
            {
                "type": "promotion",
                "id": "e4d929d5-f471-4317-9a86-a84a6c572b44",
                "name": "cart20",
                "description": "cart20",
                "automatic": false,
                "promotion_source": "rule-promotion",
                "start": "2024-04-01T18:24:06Z",
                "end": "2024-06-01T18:24:09Z"
            },
            {
                "type": "promotion",
                "id": "de19a043-a6da-4bde-b896-d17e16b77e25",
                "name": "item10",
                "description": "item10",
                "automatic": false,
                "promotion_source": "rule-promotion",
                "start": "2024-05-02T04:28:24Z",
                "end": "2024-06-02T04:28:28Z"
            }
        ]
    }
}
```

---

## Bulk Add Items to Cart

The bulk add feature allows shoppers to add an array of items to their cart in one action, rather than adding each item one at a time. Shoppers can choose to add items using either the SKU or product ID. Additionally, they can also include quantity and shipping group details in bulk requests. This minimizes the time for shoppers while adding items to their cart. Shoppers can even add multiple items with the same or different shipping groups to their cart.

When you add multiple items that qualify for free gifts to the cart, the corresponding free gifts for all eligible products are also automatically added to the cart.

An example for bulk add is:

```json
{
    "data": [
        {
            "type": "cart_item",
            "sku": "sku-1",
            "quantity": 1
        },
        {
            "type": "cart_item",
            "sku": "sku-2",
            "quantity": 1
        }
    ],
    "options": {
        "add_all_or_nothing": true
    }
}
```

With the bulk add items to cart capability, you can use one or more of the following cart actions in a transaction:

- [Add Product to Cart](/docs/api/carts/manage-carts#add-product-to-cart)
- [Add Custom Item to Cart](/docs/api/carts/manage-carts#add-custom-item-to-cart)
- [Add Promotion to Cart](/docs/api/carts/manage-carts#add-promotion-to-cart)

:::caution
The request body depends on the type of items that you want to add, such as promotion, custom or product.
:::

## Dynamic Bundles

A bundle is a purchasable product that is composed of a combination of two or more products that you want to sell together. You can create multiple components within a bundle. Each component can have one or more options. Each option is a product and a quantity. You can configure minimum and/or maximum values for the number of product options in a component that your shoppers can select. For example, you can enable a shopper to select 1 or more product options from a list of 10. These are called [dynamic bundles](/docs/api/pxm/products/products#dynamic-bundles).

Your dynamic bundles are displayed in your published catalogs. Shoppers make their selections. A shoppers selections are stored in the [configure a shopper bundle](/docs/api/pxm/catalog/configure-by-context-product) endpoint. The shoppers selections are stored in a `bundle_configuration` which is supplied in the `add product to cart` request.

 ```json
"bundle_configuration": {
                "selected_options": {
                    "games": {
                        "d7b79eb8-19d8-45ea-86ed-2324a604dd9c": 1
                    },
                    "toys": {
                        "0192ccdd-6d33-4898-87d7-c4d87f2bf8ea": 1,
                        "1aea6f97-f0d9-452c-b3c1-7fb5629ead82": 1
                    }
                }
         }
```

When a cart is checked out, the options a shopper selected are added to the order. See [order items](/docs/api/carts/get-order-items).

## Personalized Products

You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized. You can do this using the `custom_inputs` attribute. The `custom_inputs` attribute must be an object. For example, you sell greetings cards that can be printed with your shoppers personalized messages.

Once you have defined your custom inputs on a product, you must configure the custom inputs in your orders.

For example, a birthday card may have custom inputs for name and message defined for a product.

```json
{
  "custom_inputs": {
    "name": {
      "name": "Name",
      "validation_rules": {
        "type": "string"
      },
      "message": {
        "name": "Message",
        "validation_rules": {
          "type": "string"
        }
      }
    }
  }
}
```

When the product is added to the cart, those custom inputs are supplied.

```json
{
  "custom_inputs": {
    "name": {
      "name": "Fred",
      "message": "Happy Birthday"
    }
  }
}
```

If the same product has different `custom_inputs` attributes, then these are added as separate items in a cart.

The `custom_inputs` attribute is stored in the cart item and must not exceed 1MB. When a cart is [checked out](/docs/api/carts/checkout), the `custom_inputs` attribute becomes part of the [order](/docs/api/carts/get-an-order) items.

When you add products to a cart with `custom_inputs`, there are certain limitations on usage of the `custom_inputs` with the following promotion types:

- For [Free Gift Promotions](/docs/api/promotions/create-a-promotion#request), you can add `custom_inputs` to gift items.
- For [Fixed Bundle Discount Promotions](/docs/api/promotions/create-a-promotion#request), the promotion applies as long as the cart contains the bundle SKUs even when there are different `custom_inputs`.
- For [X for Y Discount Promotion](/docs/api/promotions/create-a-promotion#request) and [X for amount discount promotion](/docs/api/promotions/create-a-promotion#request), the promotion applies when there are two SKUs with the same `custom_inputs`. The promotion does not apply when there are different `custom_inputs` and the SKUs are in different line items.

## `POST` Bulk Add to Cart

```text
https://useast.api.elasticpath.com/v2/carts/:id/items
```

## Parameters

### Path parameters

| Name        | Required | Type     | Description                              |
|:------------|:---------|:---------|:-----------------------------------------|
| `id` | Required | `string` | The unique identifier of the cart that you created. |

### Headers

| Name                      | Required | Type     | Description                |
|:--------------------------|:---------|:---------|:---------------------------|
| `X-MOLTIN-CURRENCY`       | Optional | `string` | Specifies the currency to be used for the products in the cart. If you do not specify a currency, the site’s default currency is used. This header only affects the first item added to the cart. |
| `Authorization`           | Required | `string` | The Bearer token to grant access to the API. |
| `X-Moltin-Customer-Token` | Required | `string` | The unique identifier of a signed-in customer. Corresponds to the `customer_ids` attribute in a `catalog_rule` object. |
| `EP-Channel`              | Required | `string` | The channel, such as website or mobile app. Corresponds to the `channel` attribute in a `catalog_rule` object. |
| `EP-Context-Tag`          | Required | `string` | A tag defined in the store, such as `clearance`. Corresponds to the `tag` attribute in a `catalog_rule` object. |

### Body

| Name                         | Required | Type      | Description            |
|:-----------------------------|:---------|:----------|:-----------------------|
| `options.add_all_or_nothing` | Optional | `boolean` | When `true`, if an error occurs for any item, no items are added in the cart. When `false`, valid items are added in the cart and the items with errors are reported in the response. Default is `true`. |

#### Custom item body

| Name                 | Required | Type      | Description                    |
|:---------------------|:---------|:----------|:-------------------------------|
| `type`               | Required | `string`  | The type of item, such as `custom_item`. |
| `name`               | Required | `string`  | Specifies the name of the item. |
| `sku`                | Required | `string`  | The SKU of the item.           |
| `description`        | Optional | `string`  | Specifies the description of the item. |
| `quantity`           | Required | `integer` | Specifies the amount of items to add to the cart. |
| `price.amount`       | Required | `integer` | The price of the items.        |
| `price.includes_tax` | Optional | `boolean` | If true, the price includes tax. The default is true. |
| `amount`             | Required | `integer` | Specifies the total cost of the items added to the cart. |
| `tax`                | Optional | `array`   | Specifies a list of tax items to apply to the cart item. **Note**: Only administrators with client credentials can use this field. |
| `custom_inputs`      | Optional | `object`  | The custom text to be added to a product. See [custom_inputs](/docs/api/pxm/products/create-product#personalizing-products). |
| `shipping_group_id` | Optional | `string` | The shipping group ID to be added. See [Get a Cart Shipping Group by ID](/docs/ship-groups/shipping-groups/shipping-groups-api/get-a-cart-shipping-group-by-id). |

#### Cart item body

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `type`          | Required | `string` | Specifies the type, such as `cart_item`. |
| `id`            | Required | `string` | Specifies the ID of the item that you want to add to cart. **Note**: Ensure that you select only one of the two options, by SKU or by product id. |
| `sku`           | Required | `string` | Specifies the item SKU that you want to add to cart. **Note**: Ensure that you select only one of the two options, by SKU or by product id. |
| `custom_inputs` | Optional | `object` | The custom text to be added to a product. See [custom_inputs](/docs/api/pxm/products/create-product#personalizing-products) |
| `shipping_group_id` | Optional | `string` | The shipping group ID to be added. See [Get a Cart Shipping Group by ID](/docs/ship-groups/shipping-groups/shipping-groups-api/get-a-cart-shipping-group-by-id). |

#### Promotion item body

| Name   | Required | Type     | Description                                   |
|:-------|:---------|:---------|:----------------------------------------------|
| `type` | Required | `string` | Specifies the promotional item, such as `promotion_item`. |
| `code` | Required | `string` | Specifies the code for the promotional item, such as `promoCode`. |

## Request Example - Product ID

### Curl

```json
curl -X POST https://useast.api.elasticpath.com//v2/carts/:id/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -H "X-Moltin-Customer-Token: XXXX" \
     -d $ {
        "data": [
        {
        "type": "custom_item",
        "name": "My Custom Item",
        "sku": "my-custom-item",
        "description": "My first custom item!",
        "custom_inputs": {
          "personalization": "My personal message"
      },
        "quantity": 1,
        "price": {
            "amount": 20000,
            "includes_tax": true
      }
    },
    {
        "type": "cart_item",
        "id": "838520de-b64a-4a0e-9d4c-f5bb53c83ec3",
        "quantity": 1
    },
    {
        "type": "promotion_item",
        "code": "5off"
    }
  ],
        "options": {
            "add_all_or_nothing": true
    }
}
```

#### JavaScript SDK

```javascript
const reference = "XXXX";
const items = [
    {
        type: "custom_item",
        name: "My Custom Item",
        sku: "my-custom-item",
        description: "My first custom item!",
        quantity: 1,
        price: {
            amount: 20000,
            includes_tax: true,
        },
    },
    {
        type: "cart_item",
        id: "838520de-b64a-4a0e-9d4c-f5bb53c83ec3",
        quantity: 1,
    },
    {
        type: "promotion_item",
        code: "5off",
    },
];

// Where `EPCC` is an authenticated client
await EPCC.Cart(reference).BulkAdd(items);
```

## Response Example - Product ID

`201 Created`

```json
{
    "data": [
        {
            "id": "931dcd00-7621-4bb6-95bb-12fc58b10d7d",
            "type": "custom_item",
            "name": "My Custom Item",
            "description": "My first custom item!",
            "sku": "my-custom-item",
            "slug": "",
            "custom_inputs": {
                "personalization": "My personal message"
            },
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": 20000,
                "currency": "USD",
                "includes_tax": true
            },
            "value": {
                "amount": 20000,
                "currency": "USD",
                "includes_tax": true
            },
            "links": {},
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 20000,
                            "currency": "USD",
                            "formatted": "$200.00"
                        },
                        "value": {
                            "amount": 20000,
                            "currency": "USD",
                            "formatted": "$200.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 20000,
                            "currency": "USD",
                            "formatted": "$200.00"
                        },
                        "value": {
                            "amount": 20000,
                            "currency": "USD",
                            "formatted": "$200.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2020-08-27T15:33:49Z",
                    "updated_at": "2020-08-27T15:33:49Z"
                },
                "catalog_id": "92073438-7640-4ace-9670-c8c5c1a89cd7",
                "catalog_source": "pim"
            }
        },
        {
            "id": "2e5ad28c-e112-4a43-a148-37ce842f49c0",
            "type": "cart_item",
            "product_id": "838520de-b64a-4a0e-9d4c-f5bb53c83ec3",
            "name": "Item Name",
            "description": "item description",
            "sku": "item_sku",
            "slug": "item_slug",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": 5000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": 5000,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {
                "product": "https://useast.api.elasticpath.com/v2/products/838520de-b64a-4a0e-9d4c-f5bb53c83ec3"
            },
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 5000,
                            "currency": "USD",
                            "formatted": "$50.00"
                        },
                        "value": {
                            "amount": 5000,
                            "currency": "USD",
                            "formatted": "$50.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 5000,
                            "currency": "USD",
                            "formatted": "$50.00"
                        },
                        "value": {
                            "amount": 5000,
                            "currency": "USD",
                            "formatted": "$50.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2020-08-27T15:33:49Z",
                    "updated_at": "2020-08-27T15:33:49Z"
                }
            },
            "catalog_id": "92073438-7640-4ace-9670-c8c5c1a89cd7",
            "catalog_source": "pim"
        },
        {
            "id": "1425513e-8446-4e84-a72b-8e77d47f906f",
            "type": "promotion_item",
            "promotion_id": "38ef7ac1-2066-4507-90c9-2de4b49d3717",
            "name": "$5 off",
            "description": "Promotion",
            "sku": "5off",
            "slug": "",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": -500,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": -500,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {},
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        },
                        "value": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        },
                        "value": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2020-08-27T15:33:49Z",
                    "updated_at": "2020-08-27T15:33:49Z"
                }
            },
            "catalog_id": "92073438-7640-4ace-9670-c8c5c1a89cd7",
            "catalog_source": "pim"
        }
    ],
    "meta": {
        "display_price": {
            "with_tax": {
                "amount": 24500,
                "currency": "USD",
                "formatted": "$245.00"
            },
            "without_tax": {
                "amount": 24500,
                "currency": "USD",
                "formatted": "$245.00"
            },
            "tax": {
                "amount": 0,
                "currency": "USD",
                "formatted": "$0.00"
            }
        },
        "timestamps": {
            "created_at": "2020-08-27T15:33:49Z",
            "updated_at": "2020-08-27T15:33:49Z"
        },
        "messages": [
            {
                "source": {
                    "type": "promotion_item",
                    "id": "1425513e-8446-4e84-a72b-8e77d47f906f"
                },
                "title": "Promotion Added",
                "description": "Promotion has been added to cart."
            }
        ]
    }
}
```

## Request Example - SKU

```json
{
  "data": [
     {
      "type": "cart_item",
      "sku": "sku-1",
      "quantity": 1
    },
    {
      "type": "cart_item",
      "sku": "sku-2",
      "quantity": 1
    }
  ],
    "options": {
        "add_all_or_nothing": true
  }
}
```

## Response Example - SKU

`201 Created`

```json
{
    "data": [
        {
            "id": "0ac4ee19-7d8e-4b2f-b087-e4073ec801a4",
            "type": "cart_item",
            "product_id": "6648dde1-f7c1-4e77-9698-1fd541d121af",
            "name": "Product Name",
            "description": "description",
            "sku": "sku-1",
            "slug": "1",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": true,
            "unit_price": {
                "amount": 11,
                "currency": "USD",
                "includes_tax": true
            },
            "value": {
                "amount": 11,
                "currency": "USD",
                "includes_tax": true
            },
            "links": {
                "product": "https://useast.api.elasticpath.com/v2/products/6648dde1-f7c1-4e77-9698-1fd541d121af"
            },
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 11,
                            "currency": "USD",
                            "formatted": "$0.11"
                        },
                        "value": {
                            "amount": 11,
                            "currency": "USD",
                            "formatted": "$0.11"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 11,
                            "currency": "USD",
                            "formatted": "$0.11"
                        },
                        "value": {
                            "amount": 11,
                            "currency": "USD",
                            "formatted": "$0.11"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2020-10-23T23:15:24Z",
                    "updated_at": "2020-10-23T23:15:24Z"
                }
            },
            "catalog_id": "92073438-7640-4ace-9670-c8c5c1a89cd7",
            "catalog_source": "pim"
        },
        {
            "id": "18c23ab3-92e5-4671-9c28-fbfcc8f7db18",
            "type": "cart_item",
            "product_id": "acede2a9-f763-453a-a3ae-cc4f66e6dca3",
            "name": "Product Name 2",
            "description": "Description 2",
            "sku": "sku-2",
            "slug": "2",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": true,
            "unit_price": {
                "amount": 22,
                "currency": "USD",
                "includes_tax": true
            },
            "value": {
                "amount": 22,
                "currency": "USD",
                "includes_tax": true
            },
            "links": {
                "product": "https://useast.api.elasticpath.com/v2/products/acede2a9-f763-453a-a3ae-cc4f66e6dca3"
            },
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 22,
                            "currency": "USD",
                            "formatted": "$0.22"
                        },
                        "value": {
                            "amount": 22,
                            "currency": "USD",
                            "formatted": "$0.22"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 22,
                            "currency": "USD",
                            "formatted": "$0.22"
                        },
                        "value": {
                            "amount": 22,
                            "currency": "USD",
                            "formatted": "$0.22"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2020-10-23T23:15:24Z",
                    "updated_at": "2020-10-23T23:15:24Z"
                }
            },
            "catalog_id": "92073438-7640-4ace-9670-c8c5c1a89cd7",
            "catalog_source": "pim"
        }
    ],
    "meta": {
        "display_price": {
            "with_tax": {
                "amount": 33,
                "currency": "USD",
                "formatted": "$0.33"
            },
            "without_tax": {
                "amount": 33,
                "currency": "USD",
                "formatted": "$0.33"
            },
            "tax": {
                "amount": 0,
                "currency": "USD",
                "formatted": "$0.00"
            }
        },
        "timestamps": {
            "created_at": "2020-10-23T23:15:24Z",
            "updated_at": "2020-10-23T23:15:24Z"
        }
    }
}
```

## Request Example - Add items with shipping groups

```bash
curl -X POST https://useast.api.elasticpath.com/v2/carts/:id/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
    "data": [
        {
            "type": "cart_item",
            "sku": "sku1",
            "quantity": 1,
            "shipping_group_id": "cc63b873-4eff-450c-86d2-ec255160ba2e"

        },
        {
            "type": "cart_item",
            "sku": "sku2",
            "quantity": 1,
            "shipping_group_id": "5b37d927-e19f-4477-89f8-f18c2841e629"
        }
    ],
    "options": {
        "add_all_or_nothing": false
    }
}
```

## Response Example - Add items with shipping groups

`201 Created`

```json
{
    "data": [
        {
            "id": "564c710b-695e-46e4-a4cb-54114f4ec604",
            "type": "cart_item",
            "product_id": "5ed105c9-112d-4a9d-87b7-e08dcc797b0b",
            "name": "sku1",
            "description": "sku1",
            "sku": "sku1",
            "slug": "sku1",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {
                "product": "https://useast.api.elasticpath.com/v2/products/5ed105c9-112d-4a9d-87b7-e08dcc797b0b"
            },
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2023-06-29T16:50:07Z",
                    "updated_at": "2023-06-29T16:50:07Z"
                }
            },
            "catalog_id": "c1a94a13-ca0d-4793-982a-a55e77a9f9ff",
            "catalog_source": "pim",
            "shipping_group_id": "cc63b873-4eff-450c-86d2-ec255160ba2e"
        },
        {
            "id": "4089e7e2-4727-4322-a767-2a8493897887",
            "type": "cart_item",
            "product_id": "a0bb6fad-5fe6-4831-b731-91cc582bcf97",
            "name": "sku2",
            "description": "sku2",
            "sku": "sku2",
            "slug": "sku2",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {
                "product": "https://useast.api.elasticpath.com/v2/products/a0bb6fad-5fe6-4831-b731-91cc582bcf97"
            },
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2023-06-29T16:50:07Z",
                    "updated_at": "2023-06-29T16:50:07Z"
                }
            },
            "catalog_id": "c1a94a13-ca0d-4793-982a-a55e77a9f9ff",
            "catalog_source": "pim",
            "shipping_group_id": "5b37d927-e19f-4477-89f8-f18c2841e629"
        }
    ],
    "meta": {
        "display_price": {
            "with_tax": {
                "amount": 21000,
                "currency": "USD",
                "formatted": "$210.00"
            },
            "without_tax": {
                "amount": 21000,
                "currency": "USD",
                "formatted": "$210.00"
            },
            "tax": {
                "amount": 0,
                "currency": "USD",
                "formatted": "$0.00"
            },
            "discount": {
                "amount": 0,
                "currency": "USD",
                "formatted": "$0.00"
            },
            "without_discount": {
                "amount": 21000,
                "currency": "USD",
                "formatted": "$210.00"
            },
           "shipping": {
                "amount": 1000,
                "currency": "USD",
                "formatted": "$10.00"
            }

        },
        "timestamps": {
            "created_at": "2023-06-29T16:50:07Z",
            "updated_at": "2023-06-29T16:50:07Z",
            "expires_at": "2023-07-06T16:50:07Z"
        }
    }
}
```

## Request Examples

### Product ID - Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/carts/:id/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
      "data": [
    {
      "type": "custom_item",
      "name": "My Custom Item",
      "sku": "my-custom-item",
      "description": "My first custom item!",
      "quantity": 1,
      "price": {
        "amount": 20000,
        "includes_tax": true
      }
    },
    {
      "type": "cart_item",
      "id": "838520de-b64a-4a0e-9d4c-f5bb53c83ec3",
      "quantity": 1
    },
    {
      "type": "promotion_item",
      "code": "5off"
    }
  ],
      "options": {
        "add_all_or_nothing": true
  }
}'
```

### SKU - Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/carts/:reference/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
      "data": [
    {
      "type": "custom_item",
      "name": "My Custom Item",
      "sku": "my-custom-item",
      "description": "My first custom item!",
      "quantity": 1,
      "price": {
        "amount": 20000,
        "includes_tax": true
      }
    },
    {
      "type": "cart_item",
      "sku": "sku-1",
      "quantity": 1
    },
    {
      "type": "promotion_item",
      "code": "5off"
    }
  ],
      "options": {
        "add_all_or_nothing": true
  }
}'
```

### Bundle - Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/carts/:id/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "id": "5ab67bb3-b2c3-4348-af33-e370bd39b0c9",
    "type": "cart_item",
    "quantity": 1,
    "bundle_configuration": {
      "selected_options": {
        "tshirt": {
          "23759a57-13c1-4887-9ec2-fb47444751bd": 1
        },
        "comics": {
          "c7bcf7fd-1fab-4635-8ae0-7f187a9dbbce": 1,
          "d9768b40-cf28-406e-bafc-a6d130627eca": 1
        }
      }
    }
  }
}'
```

## Response Example

```json
{
  "data": {
    "id": "5ab67bb3-b2c3-4348-af33-e370bd39b0c9",
    "type": "product",
    "attributes": {
      "name": "T-shirt and comics",
      "description": "A t-shirt and two comics",
      "components": {
        "tshirt": {
          "name": "T-shirt",
          "options": [
            {
              "id": "23759a57-13c1-4887-9ec2-fb47444751bd",
              "quantity": 1,
              "type": "product"
            },
            {
              "id": "ffb9024e-82ce-49f8-b2a1-95ce0a452056",
              "quantity": 1,
              "type": "product"
            }
          ]
        },
        "comics": {
          "name": "Comics",
          "minimum": 2,
          "maximum": 2,
          "options": [
            {
              "id": "c7bcf7fd-1fab-4635-8ae0-7f187a9dbbce",
              "quantity": 1,
              "type": "product"
            },
            {
              "id": "d9768b40-cf28-406e-bafc-a6d130627eca",
              "quantity": 1,
              "type": "product"
            },
            {
              "id": "623b47ee-f43b-45ab-8939-cc6269c323ec",
              "quantity": 1,
              "type": "product"
            },
            {
              "id": "bfdf583d-aad8-4b5c-879a-06d8f4304988",
              "quantity": 1,
              "type": "product"
            }
          ]
        }
      },
      "price": {
        "USD": {
          "amount": 4000,
          "includes_tax": false
        }
      },
      "sku": "tshcom",
      "published_at": "2022-02-28T16:40:39.731Z"
    },
    "meta": {
      "bundle_configuration": {
        "selected_options": {
          "tshirt": {
            "23759a57-13c1-4887-9ec2-fb47444751bd": 1
          },
          "comics": {
            "c7bcf7fd-1fab-4635-8ae0-7f187a9dbbce": 1,
            "d9768b40-cf28-406e-bafc-a6d130627eca": 1
          }
        }
      }
    }
  }
}
```

## Response Codes

You might encounter the following response codes, depending on the scenario:

- `400 Bad Request` - An error is found, such as insufficient available stock.
- `404 Not found` - The requested product could not be found.

:::note
For items added in bulk, error codes are returned for each item individually in a response.
:::

### Bulk add error example

`404 Not Found`

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Product not found",
            "detail": "The requested product could not be found",
            "meta": {
                "sku": "sku-1"
            }
        },
        {
            "status": 400,
            "title": "Insufficient stock",
            "detail": "There is not enough stock to add Product 2 to your cart",
            "meta": {
                "id": "91b074df-2b2a-44ff-be2d-fdb4fa2ddfb4",
                "sku": "sku-2"
            }
        }
    ]
}
```

---

## Capture a Transaction(Carts-orders)

## `POST` Capture a Transaction

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/capture
```

Use this endpoint to capture a previously authorized payment. In this step, you can also pass in a custom reference, such as the payment reference from your chosen gateway.

## Parameters

### Path parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `transactionId` | Required | `string` | The UUID of the transaction to capture. |
| `orderId` | Required | `string` | The UUID of the order. |

### Headers

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name | Required | Type | Description                                                                                                                                                                                                                                                                                                       |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `custom_reference` | Optional | `string` | A custom reference that you can use to identify this transaction. If the value is different from original transaction, it will be overwritten by this value. Empty string value will clear the original value. If you omit this field in the request, the original value from the previous transaction will still persist. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transaction_id/capture \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
        "data": {
            "custom_reference": "my_custom_reference"
        }
      }
```

## Response Example

`200 OK`

```json
{
    "data": {
        "id": "bcafac29-c8ca-4293-822c-d1213e085c7c",
        "type": "transaction",
        "reference": "manual",
        "custom_reference": "my_custom_reference",
        "gateway": "manual",
        "amount": 60000,
        "currency": "GBP",
        "transaction_type": "capture",
        "status": "complete",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "239f104c-0b56-433c-a5f8-b73349196269"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 60000,
                "currency": "GBP",
                "formatted": "£600.00"
            },
            "timestamps": {
                "created_at": "2020-02-17T13:24:42Z",
                "updated_at": "2020-02-17T13:24:45Z"
            }
        }
    }
}
```

## `POST` Capture a Transaction - Manual

Use this endpoint to manually capture a previously authorized payment. 

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/capture
```

## Parameters

### Path parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `transactionId` | Required | `string` | The UUID of the transaction to capture. |
| `orderId` | Required | `string` | The UUID of the order. |

### Headers

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

|  Name | Required | Type | Description |
| --- | --- | --- | --- |                                                   
| `capture_mechanism` | Required | `string` | Always `manual`. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transaction_id/capture \
     -H "Authorization: Bearer XXXX"
     '{
        "data": {
            "capture_mechanism": "manual"
        }
      }'
```

## Response Example

`200 OK`

```Json
{
    "data": {
        "id": "09cf2557-ac72-46c4-8c66-243d065266e8",
        "type": "transaction",
        "reference": "pi_3MXQWxS5fsvVtlID1w1SejAP",
        "gateway": "elastic_path_payments_stripe",
        "amount": 20000,
        "refunded_amount": 0,
        "capture_mechanism": "manual",
        "currency": "USD",
        "transaction_type": "capture",
        "status": "complete",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "37e8325e-dd2d-48ff-9e1c-3ab82871a893"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 20000,
                "currency": "USD",
                "formatted": "$200.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2023-02-03T14:46:23Z",
                "updated_at": "2023-02-03T14:46:47Z"
            }
        }
    }
}
```

## Errors

If you manually capture an authorized transaction, you can manually mark a transaction as refunded. Therefore, you cannot perform automatic refund. The following error response is returned if you perform automatic refund:

```Json
{
    "errors": [
        {
            "status": 400,
            "title": "Error while refunding",
            "detail": "Unable to automatically refund a manually capture transaction "
        }
    ]
}
```

When you capture a transaction that was authorized but expired, the following error response example is returned from Stripe:

```json
{
    "errors": [
        {
            "status": 400,
            "title": "Payment gateway processing failed",
            "detail": "This PaymentIntent could not be captured because it has a status of canceled. Only a PaymentIntent with one of the following statuses may be captured: requires_capture.",
            "meta": {
                "error": {
                    "code": "payment_intent_unexpected_state",
                    "doc_url": "https://stripe.com/docs/error-codes/payment-intent-unexpected-state",
                    "message": "This PaymentIntent could not be captured because it has a status of canceled. Only a PaymentIntent with one of the following statuses may be captured: requires_capture.",
                    "payment_intent": {
                        "amount": 10000,
                        "amount_capturable": 0,
                        "amount_details": {
                            "tip": {}
                        },
                        "amount_received": 0,
                        "application": "ca_XXXXXXXXXXXXXXXXX",
                        "application_fee_amount": null,
                        "automatic_payment_methods": null,
                        "canceled_at": 1678903544,
                        "cancellation_reason": "automatic",
                        "capture_method": "manual",
                        "charges": {
                            "data": [
                                {
                                    "amount": 10000,
                                    "amount_captured": 0,
                                    "amount_refunded": 10000,
                                    "application": "ca_XXXXXXXXXXXXXXXXXXXXXX",
                                    "application_fee": null,
                                    "application_fee_amount": null,
                                    "balance_transaction": null,
                                    "billing_details": {
                                        "address": {
                                            "city": null,
                                            "country": null,
                                            "line1": null,
                                            "line2": null,
                                            "postal_code": null,
                                            "state": null
                                        },
                                        "email": null,
                                        "name": null,
                                        "phone": null
                                    },
                                    "calculated_statement_descriptor": "BRITISH COLUMBIA",
                                    "captured": false,
                                    "created": 1678298743,
                                    "currency": "usd",
                                    "customer": null,
                                    "description": null,
                                    "destination": null,
                                    "dispute": null,
                                    "disputed": false,
                                    "failure_balance_transaction": null,
                                    "failure_code": null,
                                    "failure_message": null,
                                    "fraud_details": {},
                                    "id": "ch_XXXXXXXXXXXXXXXXXXXXXXX",
                                    "invoice": null,
                                    "livemode": false,
                                    "metadata": {
                                        "email": "andy@example.com",
                                        "ip_address": "206.116.129.195",
                                        "order_id": "bb4e20d2-c691-45ba-9194-3b56889a8a89"
                                    },
                                    "object": "charge",
                                    "on_behalf_of": null,
                                    "order": null,
                                    "outcome": {
                                        "network_status": "approved_by_network",
                                        "reason": null,
                                        "risk_level": "normal",
                                        "risk_score": 28,
                                        "seller_message": "Payment complete.",
                                        "type": "authorized"
                                    },
                                    "paid": true,
                                    "payment_intent": "pi_XXXXXXXXXXXXXXXXX",
                                    "payment_method": "pm_XXXXXXXXXXXXXXXXX",
                                    "payment_method_details": {
                                        "card": {
                                            "brand": "visa",
                                            "checks": {
                                                "address_line1_check": null,
                                                "address_postal_code_check": null,
                                                "cvc_check": null
                                            },
                                            "country": "US",
                                            "exp_month": 3,
                                            "exp_year": 2024,
                                            "fingerprint": "6EScLzf5uXxJBcOw",
                                            "funding": "credit",
                                            "installments": null,
                                            "last4": "4242",
                                            "mandate": null,
                                            "network": "visa",
                                            "three_d_secure": null,
                                            "wallet": null
                                        },
                                        "type": "card"
                                    },
                                    "receipt_email": "john@example.com",
                                    "receipt_number": null,
                                    "receipt_url": "https://pay.stripe.com/receipts/payment/CAcaFwoVYWNjdF8xS2pBaElTNUc2WWZHUlhZKKPN6KAGMgaEeIHxYGY6LBZTPB5PVZwD5OiKRdNSUpBHhCojSpNqWw1_S4FZfH8Apayi9bClrUzwHLCg",
                                    "refunded": true,
                                    "refunds": {
                                        "data": [
                                            {
                                                "amount": 10000,
                                                "balance_transaction": null,
                                                "charge": "ch_XXXXXXXXXXXXXXXXX",
                                                "created": 1678903544,
                                                "currency": "usd",
                                                "id": "re_XXXXXXXXXXXXXXXXXXXXXXX",
                                                "metadata": {},
                                                "object": "refund",
                                                "payment_intent": "pi_XXXXXXXXXXXXXXXXXXXXX",
                                                "reason": "expired_uncaptured_charge",
                                                "receipt_number": null,
                                                "source_transfer_reversal": null,
                                                "status": "succeeded",
                                                "transfer_reversal": null
                                            }
                                        ],
                                        "has_more": false,
                                        "object": "list",
                                        "total_count": 1,
                                        "url": "/v1/charges/ch_XXXXXXXXXXXXXXXXX/refunds"
                                    },
                                    "review": null,
                                    "shipping": null,
                                    "source": null,
                                    "source_transfer": null,
                                    "statement_descriptor": null,
                                    "statement_descriptor_suffix": null,
                                    "status": "succeeded",
                                    "transfer_data": null,
                                    "transfer_group": null
                                }
                            ],
                            "has_more": false,
                            "object": "list",
                            "total_count": 1,
                            "url": "/v1/charges?payment_intent=pi_XXXXXXXXXXXXXXXXXXX"
                        },
                        "client_secret": "pi_XXXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXX",
                        "confirmation_method": "automatic",
                        "created": 1678298743,
                        "currency": "usd",
                        "customer": null,
                        "description": null,
                        "id": "pi_XXXXXXXXXXXXXXXXXXXX",
                        "invoice": null,
                        "last_payment_error": null,
                        "latest_charge": "ch_XXXXXXXXXXXXXXXXXXX",
                        "livemode": false,
                        "metadata": {
                            "email": "andy@example.com",
                            "ip_address": "206.116.129.195",
                            "order_id": "bb4e20d2-c691-45ba-9194-3b56889a8a89"
                        },
                        "next_action": null,
                        "object": "payment_intent",
                        "on_behalf_of": null,
                        "payment_method": "pm_XXXXXXXXXXXXXXXXX",
                        "payment_method_options": {
                            "card": {
                                "installments": null,
                                "mandate_options": null,
                                "network": null,
                                "request_three_d_secure": "automatic"
                            }
                        },
                        "payment_method_types": [
                            "card"
                        ],
                        "processing": null,
                        "receipt_email": "john@example.com",
                        "review": null,
                        "setup_future_usage": null,
                        "shipping": null,
                        "source": null,
                        "statement_descriptor": null,
                        "statement_descriptor_suffix": null,
                        "status": "canceled",
                        "transfer_data": null,
                        "transfer_group": null
                    },
                    "request_log_url": "https://dashboard.stripe.com/acct_XXXXXXXXXXXX/test/logs/req_VQ55E6FnJYzKvT?t=1679435427",
                    "type": "invalid_request_error"
                }
            }
        }
    ]
}
```

When you capture a transaction that was authorized but expired, the following error response example is returned from Paypal: 

```json
{
    "errors": [
        {
            "status": 422,
            "title": "Error received from paypal",
            "detail": "The requested action could not be performed, semantically incorrect, or failed business validation.",
            "meta": {
                "debug_id": "cf56b76ac5b8d",
                "details": {
                    "description": "Authorization has expired.",
                    "issue": "AUTHORIZATION_EXPIRED"
                },
                "name": "UNPROCESSABLE_ENTITY"
            }
        }
    ]
}
```
:::note
You can cancel a transaction and initiate a new transaction to make the payment. The transaction status will remain `completed` until you [cancel a transaction](/docs/api/carts/cancel-a-transaction).
::: 

When you [GET a transaction](/docs/api/carts/get-a-transaction) that was authorized but expired, the following response is returned with `payment_details` and `next_actions`:

```json
{
    "data": [
        {
            "id": "f0336c18-33ac-4945-855d-f711f7da7477",
            "type": "transaction",
            "reference": "pi_XXXXXXXXXXXXXXXXX",
            "gateway": "elastic_path_payments_stripe",
            "amount": 10000,
            "refunded_amount": 0,
            "currency": "USD",
            "transaction_type": "authorize",
            "status": "complete",
            "relationships": {
                "order": {
                    "data": {
                        "type": "order",
                        "id": "bb4e20d2-c691-45ba-9194-3b56889a8a89"
                    }
                }
            },
            "meta": {
                "display_price": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                },
                "display_refunded_amount": {
                    "total": {
                        "amount": 0,
                        "currency": "USD",
                        "formatted": "$0.00"
                    }
                },
                "timestamps": {
                    "created_at": "2023-03-08T18:05:43Z",
                    "updated_at": "2023-03-08T18:05:44Z"
                }
            },
            "payment_details": {
                "detailed_status": "expired_uncaptured_charge"
            },
            "next_actions": [
                "cancel",
                "capture"
            ]
        }
    ]
}
```

---

## Configure Elastic Path Composable Commerce Stripe Plugin

The Elastic Path Composable Commerce Stripe Plugin enables Commerce to securely connect to Stripe for payment capabilities. This plugin provides a more secure way to authenticate. If you are using Stripe or Stripe Intent gateway, you must install the Stripe plugin in your [Stripe Dashboard](https://dashboard.stripe.com/login).

## Steps to Configure Elastic Path Composable Commerce Stripe Plugin

1. Login to your [Stripe Dashboard](https://dashboard.stripe.com/login).
2. Ensure that you are in either a test mode or a production mode, depending on whether you are configuring a production environment or a test environment. You can switch the modes using the toggle in the top-right corner of the dashboard.
3. Install the Elastic Path Composable Commerce Stripe Plugin within the Stripe Dashboard.
4. Once installed, navigate to the **View App Settings**, and then select **View API Keys**.
5. Copy the **Publishable key** value. This key is used when configuring Payment Elements on your front-end.
6. Copy the **Secret key** value. Paste this key in Commerce Manager or Payment gateway APIs for [Stripe Payment Intents](/docs/commerce-manager/payments/configure-other-payment-gateways#enabling-stripe-payment-intents) gateways to make the payments.

---

## Confirm an Order

## `POST` Confirm an Order

```http
https://useast.api.elasticpath.com/v2/orders/:orderID/confirm
```

Use this endpoint to confirm the stripe payment intent and synchronize it with Commerce Cloud. See [Cart Payment Intent](/docs/api/carts/create-cart-payment-intent).

## Parameters

### Path parameters

| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `orderID` | Required | `string` | The ID of the order that you want to confirm. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name   | Required | Type     | Description |
|:-------|:---------|:---------|:------------|
| `options` | Optional | `object` | Defines various Stripe options, such as `order_id` and `statement_descriptor`, when confirming an order that is linked to a Payment Intent. Refer to [Stripe Documentation](https://stripe.com/docs/api/payment_intents) for additional available `options`. | 
| `options.metadata.order_id` | Optional | `string` | Represents the unique identifier of the order linked to the Payment Intent. |
| `options.metadata.statement_descriptor` | Optional | `string` | Represents description of a charge on your shoppers statements. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderID/confirm \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $ {
      "data": {
        "options": {
            "metadata": {
                "order_id": "{{orderID}}",
                "statement_descriptor": "Confirmed intent"
            }
        }
    }
}
```

## Response Example

```json
{
    "data": {
        "id": "33693acb-ef86-49b1-88ff-29ecdfad1e3e",
        "type": "transaction",
        "reference": "pi_xxxxxxxxxxxxxxxxxx",
        "name": "Stripe Payment Intent",
        "custom_reference": "pi_xxxxxxxxxxxxxxxxxx",
        "gateway": "elastic_path_payments_stripe",
        "amount": 10000,
        "refunded_amount": 0,
        "currency": "USD",
        "transaction_type": "authorize",
        "status": "pending",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "d99142c0-1bfb-407a-a4a6-ed0e7641cf9a"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 10000,
                "currency": "USD",
                "formatted": "$100.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2024-01-08T21:43:08Z",
                "updated_at": "2024-01-08T21:43:08Z"
            }
        },
        "payment_intent": {
            "amount": 10000,
            "amount_capturable": 0,
            "amount_details": {
                "tip": {
                    "amount": 0
                }
            },
            "amount_received": 0,
            "application": {
                "deleted": false,
                "id": "ca_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                "name": "",
                "object": ""
            },
            "application_fee_amount": 0,
            "automatic_payment_methods": {
                "enabled": true
            },
            "canceled_at": 0,
            "cancellation_reason": "",
            "capture_method": "manual",
            "charges": {
                "data": [],
                "has_more": false,
                "total_count": 0,
                "url": "/v1/charges?payment_intent=pi_xxxxxxxxxxxxxxxxxx"
            },
            "client_secret": "pi_xxxxxxxxxxxxxxxxxx_secret_xxxxxxxxxxxxxxxxxx",
            "confirmation_method": "automatic",
            "created": 1704750178,
            "currency": "usd",
            "customer": null,
            "description": "",
            "id": "pi_xxxxxxxxxxxxxxxxxx",
            "invoice": null,
            "last_payment_error": null,
            "livemode": false,
            "metadata": {
                "order_id": "d99142c0-1bfb-407a-a4a6-ed0e7641cf9a",
                "statement_descriptor": "Confirmed intent"
            },
            "next_action": null,
            "object": "payment_intent",
            "on_behalf_of": null,
            "payment_method": null,
            "payment_method_options": {
                "acss_debit": null,
                "affirm": null,
                "afterpay_clearpay": null,
                "alipay": null,
                "au_becs_debit": null,
                "bacs_debit": null,
                "bancontact": null,
                "blik": null,
                "boleto": null,
                "card": {
                    "capture_method": "",
                    "installments": null,
                    "mandate_options": null,
                    "network": "",
                    "request_three_d_secure": "automatic",
                    "setup_future_usage": "",
                    "statement_descriptor_suffix_kana": "",
                    "statement_descriptor_suffix_kanji": ""
                },
                "card_present": null,
                "customer_balance": null,
                "eps": null,
                "fpx": null,
                "giropay": null,
                "grabpay": null,
                "ideal": null,
                "interac_present": null,
                "klarna": null,
                "konbini": null,
                "link": {
                    "capture_method": "",
                    "persistent_token": "",
                    "setup_future_usage": ""
                },
                "oxxo": null,
                "p24": null,
                "paynow": null,
                "promptpay": null,
                "sepa_debit": null,
                "sofort": null,
                "us_bank_account": null,
                "wechat_pay": null
            },
            "payment_method_types": [
                "card",
                "link"
            ],
            "processing": null,
            "receipt_email": "john@example.com",
            "review": null,
            "setup_future_usage": "",
            "shipping": null,
            "source": null,
            "statement_descriptor": "",
            "statement_descriptor_suffix": "",
            "status": "requires_payment_method",
            "transfer_data": null,
            "transfer_group": ""
        },
        "payment_details": {
            "detailed_status": "requires_payment_method"
        },
        "next_actions": [
            "cancel"
        ]
    }
}
```

---

## Include for Custom Discounts

## `GET` Include Custom Discounts

You can use `include=custom_discounts` to retrieve detailed information about the custom discounts associated with an order.

```http
https://useast.api.elasticpath.com/v2/orders/:id?include=custom_discounts
```
## Parameters

### Path parameters

| Name | Required | Type     | Description          |
|:-----|:---------|:---------|:---------------------|
| `id` | Required | `string` | The ID of the order. |

### Query parameters 

| Name | Required | Type     | Description          |
|:-----|:---------|:---------|:---------------------|
| `include` | Required | `string` | The custom discounts for the order. |

## Request Example - Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/orders/:id?include=custom_discounts \
     -H "Authorization: Bearer XXXX"
```

## Response Example

`200 OK`

```JSon
{
    "data": {
        "id": "a51a680e-9570-4f8d-9bbc-bd3c9fcd9ea3",
        "type": "order",
        "status": "incomplete",
        "payment": "unpaid",
        "shipping": "unfulfilled",
        "anonymized": false,
        "customer": {
            "name": "John Doe",
            "email": "andy@example.com"
        },
        "shipping_address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "phone_number": "123-456-1111",
            "company_name": "Elasticpath",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "city": "Sunny Town",
            "postcode": "v1v 1v1",
            "county": "BC",
            "country": "CA",
            "instructions": ""
        },
        "billing_address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "company_name": "Elasticpath",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "city": "Sunny Town",
            "postcode": "v1v 1v1",
            "county": "BC",
            "country": "CA"
        },
        "links": {},
        "meta": {
            "display_price": {
                "with_tax": {
                    "amount": 8500,
                    "currency": "USD",
                    "formatted": "$85.00"
                },
                "without_tax": {
                    "amount": 8500,
                    "currency": "USD",
                    "formatted": "$85.00"
                },
                "tax": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "discount": {
                    "amount": -1500,
                    "currency": "USD",
                    "formatted": "-$15.00"
                },
                "balance_owing": {
                    "amount": 8500,
                    "currency": "USD",
                    "formatted": "$85.00"
                },
                "paid": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "authorized": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                },
                "without_discount": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                }
            },
            "timestamps": {
                "created_at": "2023-04-19T23:08:57Z",
                "updated_at": "2023-04-19T23:08:57Z"
            }
        },
        "relationships": {
            "items": {
                "data": [
                    {
                        "type": "item",
                        "id": "8addeb0a-3117-4583-bb92-efd7a7aa91b5"
                    }
                ]
            },
            "custom_discounts": {
                "data": [
                    {
                        "type": "custom_discount",
                        "id": "4b3ec5f2-941f-4125-89d7-5885b3e9782b"
                    }
                ]
            }
        }
    },
    "included": {
        "custom_discounts": [
            {
                "amount": {
                    "amount": -500,
                    "currency": "USD"
                },
                "type": "custom_discount",
                "id": "3e36ad8e-cf3e-463d-8332-ef569ffc819c",
                "external_id": "item custom discount",
                "discount_engine": "Custom Discount Engine",
                "description": "custom discount description",
                "discount_code": "item custom-code"
            },
            {
                "amount": {
                    "amount": -1000,
                    "currency": "USD"
                },
                "type": "custom_discount",
                "id": "4b3ec5f2-941f-4125-89d7-5885b3e9782b",
                "external_id": "cart custom discount",
                "discount_engine": "Custom Discount Engine",
                "description": "custom discount description",
                "discount_code": "cart custom-code"
            }
        ]
    }
}
```

---

## Elastic Path Payments Powered by Stripe

The Elastic Path Payments Powered by Stripe integration supports the following payment methods:

- `authorize`
- `capture`
- `confirm`
- `purchase`
- `refund`

:::note
You can contact Elastic Path sales or [customer success team](mailto:customersuccess@elasticpath.com) to get more information about Elastic Path Payments powered by Stripe and to check whether it will work for you.
:::

## Authorization or Purchase - `POST` Pay using Token or Source

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/payments
```

### Parameters

#### Path parameters

| Name      | Required | Type     | Description                                |
|:----------|:---------|:---------|:-------------------------------------------|
| `orderId` | Required | `string` | The universally unique identifier of the order that you want to pay for. |

#### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

#### Body

| Name                      | Required | Type      | Description               |
|:--------------------------|:---------|:----------|:--------------------------|
| `options.idempotency_key` | Optional | `string`  | Provides the option to send a Stripe Idempotency Key. |
| `options.receipt_email`   | Optional | `string`  | Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode. |
| `payment`                 | Required | `string`  | Specifies the Stripe token or source. |
| `options.customer`        | Optional | `string`  | Specifies the Stripe customer ID. This is required if you want to send a [source](https://stripe.com/docs/api/sources). |
| `method`                  | Required | `string`  | Specifies the transaction method, such as `purchase` or `authorize`. |
| `amount`                  | Optional | `integer` | Specifies the amount to be paid for the transaction. |
| `gateway`                 | Required | `string`  | Specifies the gateway. You must use `elastic_path_payments_stripe` as the required gateway. |

### Request examples

We recommend that you use the payment method or source with Stripe payments. For more information about generating a payment method on the client-side, see the [Stripe Elements](https://stripe.com/docs/payments/elements) documentation.

:::caution
When you pass `source` instead of a `token`, ensure that you include the Stripe customer ID in the request.
:::

:::note
If you are using Stripe API, pass your `Stripe-Account` ID in the header to make the payment. For example, see the following request:

```bash
curl https://api.stripe.com/v1/payment_methods \
  -u pk_live_EP_STRIPE_PUBLISHABLE_KEY: \
-H Stripe-Account:acct_xxxxxxx\
  -d type=card \
  -d "card[number]"=xxxxxxxxxxxx \
  -d "card[exp_month]"=6 \
  -d "card[exp_year]"=2023 \
  -d "card[cvc]"=314
```

:::

#### Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/payments \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
        "data": {
          "gateway": "elastic_path_payments_stripe",
          "method": "purchase",
          "amount": 5499,
          "payment": "pm_card_threeDSecureRequired",
          "options": {
            "receipt_email": "john@example.com"
          }
        }
      }
```

#### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
});
const id = "XXXX";
const payment = {
    gateway: "elastic_path_payments_stripe",
    method: "purchase",
    payment: "pm_card_threeDSecureRequired",
};
Moltin.Orders.Payment(id, payment).then(() => {
    // Do something
});
```

### Response example

`201 Created`

:::note
The `x` values in the `"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` are replaced with the returned values.
:::

```json
{
    "data": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "type": "transaction",
        "reference": "pi_xxxxxxxxxxxxx",
        "gateway": "elastic_path_payments_stripe",
        "amount": 5499,
        "currency": "USD",
        "transaction-type": "purchase",
        "transaction_type": "purchase",
        "status": "pending",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 5499,
                "currency": "USD",
                "formatted": "$54.99"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "created_at": "2019-08-28T10:40:21.925Z",
            "timestamps": {
                "created_at": "2019-08-28T10:40:21Z",
                "updated_at": "2019-08-28T10:40:23Z"
            }
        },
        "client_parameters": {
            "token": "pi_xxxxxxxxxxxxxxxx",
            "secret": "pi_xxxxxxxxxxxxxx_secret_xxxxxxxxxxxxxx"
        }
    }
}
```

## Authorization or Purchase - `POST` Pay using Stripe Payment Element

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/payments
```

### Parameters

#### Path parameters

| Name      | Required | Type     | Description                                |
|:----------|:---------|:---------|:-------------------------------------------|
| `orderId` | Required | `string` | The universally unique identifier of the order that you want to pay for. |

#### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

#### Body

:::note
If both `payment_method_types` and ` automatic_payment_methods` are not enabled, the Stripe default, which is `card`, will be used. Attempting to set both `payment_method_types` and `automatic_payment_methods` to `true` will result in an error as Stripe doesn't allow both options to be enabled at the same time.
:::

| Name                    | Required | Type     | Description                  |
|:------------------------|:---------|:---------|:-----------------------------|
| `gateway`               | Required | `string` | Specifies the gateway. You must use `elastic_path_payments_stripe` as the required gateway. |
| `method`                | Required | `string` | Specifies the transaction method, such as `purchase` or `authorize`. |
| `options.receipt_email` | Optional | `string` | Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode. |
| `options.automatic_payment_methods.enabled` | Optional | `boolean` | When set to `true`, it displays all enabled payment methods from the [Stripe dashboard](https://dashboard.stripe.com/login). When set to `false`, the Stripe default, which is `card`, will be used. |
| `payment_method_types`  | Required | `string` | Specifies the Stripe payment method types configured for the store. See [Stripe Documentation](https://stripe.com/docs/api/payment_intents/create#create_payment_intent-payment_method_types). |

### Request examples

#### Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/payments \
     -H "Authorization: Bearer XXXX" \
     -d $ {
       "data": {
         "gateway": "elastic_path_payments_stripe",
         "method": "purchase",
         "options": {
           "receipt_email": "john@example.com"
           "automatic_payment_methods": {
                "enabled": true
        }
    }
  }
}
```

#### JavaScript SDK

```javascript
const MoltinGateway = require('@moltin/sdk').gateway
const Moltin = MoltinGateway({
  client_id: 'X'
})
const id = 'XXXX'
const payment = {
  gateway: 'elastic_path_payments_stripe',
  method: 'purchase',
  options: {
    receipt_email: "john@example.com"
  },
  payment_method_types: ["link", "card"],
}

Moltin.Orders.Payment(id, payment).then(() => {
  // Do something
})
```

### Response example

`201 Created`

```json
{
    "data": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "type": "transaction",
        "reference": "pi_xxxxxxxxxxxxxx",
        "gateway": "elastic_path_payments_stripe",
        "amount": 20000,
        "refunded_amount": 0,
        "currency": "USD",
        "transaction_type": "purchase-setup",
        "status": "pending",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 20000,
                "currency": "USD",
                "formatted": "$200.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2022-07-18T22:16:11Z",
                "updated_at": "2022-07-18T22:16:32Z"
            }
        },
        "client_parameters": {
            "token": "pi_xxxxxxxxxxxxxx",
            "secret": "pi_xxxxxxxxxxxxxx_secret_xxxxxxxxxxxxxx"
        },
        "payment_intent": {
            "amount": 20000,
            "amount_capturable": 0,
            "amount_details": {
                "tip": {}
            },
            "amount_received": 0,
            "application": {
                "deleted": false,
                "id": "ca_KH5gI4U1QcTNYo08rUpmVAGds0YBp0ZG",
                "name": "",
                "object": ""
            },
            "application_fee_amount": null,
            "automatic_payment_methods": {
                "enabled": true
            },
            "canceled_at": null,
            "cancellation_reason": null,
            "capture_method": "manual",
            "charges": {
                "data": [],
                "has_more": false,
                "object": "list",
                "total_count": 0,
                "url": "/v1/charges?payment_intent=pi_xxxxxxxxxxxxxx"
            },
            "client_secret": "pi_xxxxxxxxxxxxxx_secret_xxxxxxxxxxxxxx",
            "confirmation_method": "automatic",
            "created": 1658182571,
            "currency": "usd",
            "customer": null,
            "description": null,
            "id": "pi_xxxxxxxxxxxxxx",
            "invoice": null,
            "last_payment_error": null,
            "livemode": false,
            "metadata": {
                "email": "andy@example.com",
                "ip_address": "##.###.###.###",
                "order_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            },
            "next_action": null,
            "object": "payment_intent",
            "on_behalf_of": null,
            "payment_method": null,
            "payment_method_options": {
                "acss_debit": null,
                "affirm": null,
                "afterpay_clearpay": null,
                "alipay": null,
                "au_becs_debit": null,
                "bacs_debit": null,
                "bancontact": {
                    "preferred_language": "en",
                    "setup_future_usage": ""
                },
                "blik": null,
                "boleto": null,
                "card": {
                    "capture_method": "",
                    "installments": null,
                    "mandate_options": null,
                    "network": "",
                    "request_three_d_secure": "automatic",
                    "setup_future_usage": "",
                    "statement_descriptor_suffix_kana": "",
                    "statement_descriptor_suffix_kanji": ""
                },
                "card_present": null,
                "customer_balance": null,
                "eps": {
                    "setup_future_usage": ""
                },
                "fpx": null,
                "giropay": {
                    "setup_future_usage": ""
                },
                "grabpay": null,
                "ideal": {
                    "setup_future_usage": ""
                },
                "interac_present": null,
                "klarna": null,
                "konbini": null,
                "link": {
                    "capture_method": "",
                    "persistent_token": "",
                    "setup_future_usage": ""
                },
                "oxxo": null,
                "p24": {
                    "setup_future_usage": ""
                },
                "paynow": null,
                "promptpay": null,
                "sepa_debit": {
                    "mandate_options": null,
                    "setup_future_usage": ""
                },
                "sofort": null,
                "us_bank_account": null,
                "wechat_pay": null
            },
            "payment_method_types": [
                "card",
                "bancontact",
                "eps",
                "giropay",
                "ideal",
                "p24",
                "sepa_debit",
                "link"
            ],
            "processing": null,
            "receipt_email": "john@example.com",
            "review": null,
            "setup_future_usage": "",
            "shipping": null,
            "source": null,
            "statement_descriptor": "",
            "statement_descriptor_suffix": "",
            "status": "requires_payment_method",
            "transfer_data": null,
            "transfer_group": ""
        },
        "payment_details": {
            "detailed_status": "requires_payment_method"
        },
        "next_actions": [
            "cancel"
        ]
    }
}
```
## Authorization or Purchase - `POST` Pay using 3D Secure

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/payments
```

### Parameters

#### Path parameters

| Name      | Required | Type     | Description                                |
|:----------|:---------|:---------|:-------------------------------------------|
| `orderId` | Required | `string` | The universally unique identifier of the order that you want to pay for. |

#### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

#### Body

| Name                    | Required | Type     | Description                  |
|:------------------------|:---------|:---------|:-----------------------------|
| `gateway`               | Required | `string` | Specifies the gateway. You must use `elastic_path_payments_stripe` as the required gateway. |
| `method`                | Required | `string` | Specifies the transaction method, such as `purchase` or `authorize`. |
| `payment` |  Required | `string` | Use `pm_card_threeDSecureRequired` or `pm_card_threeDSecure2Required`. |
| `options.return_url` | Optional | `string` | 	Indicates the URL to redirect the user in the case of approved payment.|
| `options.receipt_email` | Optional | `string` | Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode. |
| `options.confirm` | Optional | `boolean` | Set to `true` to confirm the payment. Default value is `true`. |
| `options.execute_threed` | Optional | `boolean` | Set this field to `true` to use 3D secure. Default value is `true`. |
| `confirmation_method`  | Required | `string` | Specifies confirmation method for payment. Values can be set to `manual` or `automatic`. Default is `automatic`. |

### Request Example - Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
       "data": {
         "gateway": "elastic_path_payments_stripe",
         "method": "authorize",
         "payment": "pm_card_threeDSecureRequired",
         "options": {
            "return_url": "https://your.frontend.url/return",
            "receipt_email": "john@example.com",
            "confirm": true,
            "execute_threed": true,
            "confirmation_method": "manual"

         }
       }
     }
```

### Response Example

`200 OK`

```Json
{
    "data": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "type": "transaction",
        "reference": "pi_xxxxxxxxxxxxxx",
        "gateway": "elastic_path_payments_stripe",
        "amount": 20000,
        "refunded_amount": 0,
        "currency": "USD",
        "transaction_type": "authorize",
        "status": "pending",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 20000,
                "currency": "USD",
                "formatted": "$200.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2023-03-09T14:01:32Z",
                "updated_at": "2023-03-09T14:01:33Z"
            }
        },
        "client_parameters": {
            "token": "pi_xxxxxxxxxxxxxx",
            "secret": "pi_xxxxxxxxxxxxxx_secret_xxxxxxxxxxxxxx"
        },
        "payment_intent": {
            "amount": 20000,
            "amount_capturable": 0,
            "amount_details": {
                "tip": {}
            },
            "amount_received": 0,
            "application": "ca_xxxxxxxxxxxxxx",
            "application_fee_amount": null,
            "automatic_payment_methods": null,
            "canceled_at": null,
            "cancellation_reason": null,
            "capture_method": "manual",
            "charges": {
                "data": [],
                "has_more": false,
                "object": "list",
                "total_count": 0,
                "url": "/v1/charges?payment_intent=pi_xxxxxxxxxxxxxx"
            },
            "client_secret": "pi_xxxxxxxxxxxxxx_secret_xxxxxxxxxxxxxx",
            "confirmation_method": "manual",
            "created": 1678370492,
            "currency": "usd",
            "customer": null,
            "description": null,
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "invoice": null,
            "last_payment_error": null,
            "latest_charge": null,
            "livemode": false,
            "metadata": {
                "email": "andy@example.com",
                "ip_address": "174.91.171.193",
                "order_id": "73f1bd38-8dda-441a-98b3-57d05af4d9ac"
            },
            "next_action": {
                "redirect_to_url": {
                    "return_url": "https://your.frontend.url/return",
                    "url": "https://hooks.stripe.com/redirect/authenticate/src_1Mjk2CS5G6YfGRXYqAAR6EsF?client_secret=src_client_secret_XEsFaMSCQwEeDnVUbQUa9P8P&source_redirect_slug=test_YWNjdF8xS2pBaElTNUc2WWZHUlhZLF9OVWpWT2N0eDJoNGRjQkhJMnhsUkUyNmdpd2NkM0xk01003bGfQmde"
                },
                "type": "redirect_to_url"
            },
            "object": "payment_intent",
            "on_behalf_of": null,
            "payment_method": "pm_xxxxxxxxxxxx",
            "payment_method_options": {
                "card": {
                    "installments": null,
                    "mandate_options": null,
                    "network": null,
                    "request_three_d_secure": "automatic"
                }
            },
            "payment_method_types": [
                "card"
            ],
            "processing": null,
            "receipt_email": "john@example.com",
            "review": null,
            "setup_future_usage": null,
            "shipping": null,
            "source": null,
            "statement_descriptor": null,
            "statement_descriptor_suffix": null,
            "status": "requires_action",
            "transfer_data": null,
            "transfer_group": null
        },
        "payment_details": {
            "detailed_status": "requires_action"
        },
        "next_actions": [
            "cancel"
        ]
    }
}
```

## Confirmation - `POST` Confirm the Security Validation

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/confirm
```

### Parameters

#### Path parameters

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `orderId`       | Required | `string` | The universally unique identifier of the order that you want to pay for. |
| `transactionId` | Required | `string` | The universally unique identifier of the transaction that requires client action to process validation. |

#### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Request example

If the response for the authorization or purchase request consists of `client_parameters`, Stripe might required client action to perform a 3D Secure validation. Use the Stripe client libraries and process the 3D Secure validation. When the validation succeeds, continue the payment processing by making a request as in the following example:

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/confirm \
     -H "Authorization: Bearer XXXX" \
     -d $ {
        "data": {
        }
      }
```

### Response example

`201 Created`

:::note
The `x` values in the `"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` are replaced with the returned values.
:::

```json
{
    "data": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "type": "transaction",
        "reference": "xxxxxx",
        "gateway": "elastic_path_payments_stripe",
        "amount": 100,
        "currency": "USD",
        "transaction_type": "purchase",
        "status": "complete",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 100,
                "currency": "USD",
                "formatted": "$100.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2020-05-25T20:58:57Z",
                "updated_at": "2020-05-25T13:59:01-07:00"
            }
        }
    }
}
```

## Confirmation - `POST` Capture the Payment Authorization

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/capture
```

Use this endpoint to capture a transaction initiated by the shopper. Usually capture does not occur at the same time as authorization. For more information, see the [Capture](/docs/api/carts/payments#capture) section.

### Parameters

#### Path parameters

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `orderId`       | Required | `string` | The universally unique identifier of the order that you want to pay for. |
| `transactionId` | Required | `string` | The universally unique identifier of the successful transaction for this payment. |

#### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Request example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/capture \
     -H "Authorization: Bearer XXXX"
```

### Response example

`201 Created`

:::note
The `x` values in the `"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` are replaced with the returned values.
:::

```json
{
    "data": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "type": "transaction",
        "reference": "xxxxxx",
        "gateway": "elastic_path_payments_stripe",
        "amount": 100,
        "currency": "USD",
        "transaction_type": "capture",
        "status": "complete",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 100,
                "currency": "USD",
                "formatted": "$100.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2020-05-25T20:58:57Z",
                "updated_at": "2020-05-25T13:59:01-07:00"
            }
        }
    }
}
```

## Refund - `Post` Refund the Payment

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/refund
```

Use this endpoint to refund the amount initiated by the shopper.

### Parameters

#### Path parameters

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `orderId`       | Required | `string` | The universally unique identifier of the order that you want to pay for. |
| `transactionId` | Required | `string` | The universally unique identifier of the successful transaction for this payment. |

#### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

#### Body

| Name                    | Required | Type      | Description                 |
|:------------------------|:---------|:----------|:----------------------------|
| `amount`                | Required | `integer` | Specifies the amount to be refunded. |
| `options.note_to_payer` | Optional | `string`  | Specifies the reason for the refund. It appears in both the transaction history of the payer and the emails that the payer receives. |

### Request example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/refund \
     -H "Authorization: Bearer XXXX"
     "data": {
     "amount": 1,
      "options": {
       "note_to_payer": "Test note to payer"
    }
  }
}
```

### Response example

`200 OK`

```json
{
    "data": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "type": "transaction",
        "reference": "pi_3Kr4EBHGgiZNYgWz1eio9cFS",
        "gateway": "elastic_path_payments_stripe",
        "amount": 80000,
        "refunded_amount": 2,
        "refund_mechanism": "automatic",
        "currency": "GBP",
        "transaction_type": "refund",
        "status": "complete",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 80000,
                "currency": "GBP",
                "formatted": "£800.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 2,
                    "currency": "GBP",
                    "formatted": "£0.02"
                }
            },
            "timestamps": {
                "created_at": "2022-04-21T17:55:38Z",
                "updated_at": "2022-04-22T15:37:07Z"
            }
        }
    }
}
```

---

## Refund a Payment

import Video from "/src/components/CardDisplay/video";

There are two ways to refund; through your payment gateway and mark it refunded in Commerce Manager, or directly through Commerce Manager or API.

- **Mark as Refunded**: You can manually mark a transaction as refunded. Before you can mark the order as refunded, you need to handle the actual refund on your side with your payment provider. **Mark as Refunded** is a full refund made to the transaction.
- **Refund** through Composable Commerce: You can process a full or partial refund to a supported payment provider directly from Commerce Manager or API by providing the refund amount. When you start the refund process, the request is directly sent to the payment gateway.

:::caution
If you use manual gateway for partial or full refund, you need to handle the actual refund on your side with your payment provider.
:::

With split payments, you can initiate a refund for a specific transaction. You can only initiate a refund against a transaction if the order status is `complete` and payment status is `paid`, or the order is `cancelled`.

- Ensure that the transaction is already captured and complete to refund a specific transaction. The maximum refund amount is equal to the transaction amount. You can issue the refund to the original payment method of the transaction.
- Each transaction must be refunded independently to fully refund an order with multiple transactions.
- Refund amount cannot exceed the total transaction amount and the order amount.
- You can initiate multiple partial refunds for a single transaction. For example, the total order amount is $100 with two transactions, where the first transaction value is $60 and the second is $40. In this case, you can initiate multiple partial refunds for the first transaction until the total refunded amount is equal to $60. Similarly, you can initiate multiple partial refunds for the second transaction until the total refunded amount is $40.

## `POST` Refund a Full Payment

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/refund
```

### Parameters

#### Path parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `transactionId` | Required | `string` | The UUID of the transaction you want to refund. |
| `orderId` | Required | `string` | The UUID of the order. |

#### Headers

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

#### Body

| Name     | Required | Type      | Description                                                                                                                                                                                                                                                                                                                                              |
|----------|----------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `amount` | Optional | `integer` | The amount value to be refunded. If this field is not provided, it will be considered as manual refund (Mark as Refunded) and the refund process must be manually handled via payment provider. If the amount value is same as payment value, then it will be treated as a full refund and sent to the payment provider to process refund automatically. |

### Request Example - Mark as Refunded (manual)

When you manually mark as refunded, you do not need to provide any request body.

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/refund \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

### Request Example - Full Refund (automatic)

When you want to full refund the payment via payment provider automatically, you need to provide the amount value in request body.

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/refund \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
            "data": {
            "amount": <Total of captured amount>,
          }
        }'
```

#### Optional parameters

:::note
Ensure that you use the correct `option` parameter for your payment provider. For example, PayPal Express uses the `note` parameter where you can provide comments about the refund.
:::

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/refund \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
            "data": {
            "amount": <Total of captured amount>,
            "options": {
                "note": "PayPal Express users"
          }
        }'
```

### Response example

`200 OK`

```json
{
    "data": {
        "id": "6112f8b0-ce4e-4ef8-a117-cb741654efa5",
        "type": "transaction",
        "reference": "B8PP0D6ABE57",
        "gateway": "<Your payment provider>",
        "amount": 10000,
        "refunded_amount": 10000,
        "refund_mechanism": "automatic",
        "currency": "USD",
        "transaction_type": "refund",
        "status": "complete",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "1b031452-b048-43b9-a06c-feafe6e4bc31"
                }
            },
            "timestamps": {
                "created_at": "2020-07-03T21:07:45Z",
                "updated_at": "2020-07-03T14:09:12-07:00"
            }
        },
        "meta": {
            "display_price": {
                "amount": 10000,
                "currency": "USD",
                "formatted": "$100.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                }
            },
            "timestamps": {
                "created_at": "2020-07-03T21:10:14Z",
                "updated_at": "2020-07-03T14:11:59-07:00"
            }
        },
        "meta": {
            "display_price": {
                "amount": 10000,
                "currency": "USD",
                "formatted": "$100.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 10000,
                    "currency": "USD",
                    "formatted": "$100.00"
                }
            },
            "timestamps": {
                "created_at": "2020-07-03T21:10:14Z",
                "updated_at": "2020-07-03T14:11:59-07:00"
            }
        }
    }
}
```

## `POST` Refund a Partial Payment

```http
https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/refund
```

### Parameters

#### Path parameters

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `transactionId` | Required | `string` | The UUID of the transaction you want to refund. |
| `orderId` | Required | `string` | The UUID of the order. |

#### Headers

| Name | Required | Type | Description |
| --- | --- | --- | --- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

#### Body

| Name     | Required | Type      | Description                                                                                                                                                              |
|----------|----------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `amount` | Required | `integer` | The amount value to be refunded. Partial refund requires the amount value to be specified. The request will be sent to the payment provider and processed automatically. |

### Request example - Curl

:::note
Ensure that you list the amount of the refund in cents. For example, for a refund of $10.00, put `1000`. Also ensure that you use the correct `option` parameter for your payment provider. For example, PayPal Express uses the `note` parameter where you can provide comments about the refund.
:::

```bash
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/transactions/:transactionId/refund \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $' {
            "data": {
            "amount": 5000,
            "options": {
                "note": "PayPal Express users"
           }
        }'
```

### Response example

`200 OK`

```json
{
    "data": {
        "id": "d1e0b7db-3112-47ee-aaf9-c96d6a94bbcc",
        "type": "transaction",
        "reference": "B8PP0D6494BD",
        "gateway": "<Your payment provider>",
        "amount": 10000,
        "refunded_amount": 5000,
        "refund_mechanism": "automatic",
        "currency": "USD",
        "transaction_type": "refund",
        "status": "complete",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "09a46cb9-4eb7-49c9-97f1-e0c8085017a6"
                }
            }
        },
        "meta": {
            "display_price": {
                "amount": 10000,
                "currency": "USD",
                "formatted": "$100.00"
            },
            "display_refunded_amount": {
                "total": {
                    "amount": 5000,
                    "currency": "USD",
                    "formatted": "$50.00"
                }
            },
            "timestamps": {
                "created_at": "2020-06-26T23:06:02Z",
                "updated_at": "2020-06-26T23:06:50Z"
            }
        }
      }
}
```

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/68MaMVR--J4"
  mediaType="embed"
  title="Managing Refunds in Composable Commerce"
  className=""
/>
<Video
  mediaSrc="https://www.youtube.com/embed/K5zOqDlZeZ8"
  mediaType="embed"
  title="Stripe Refund"
  className=""
/>

---

## Update Cart Payment Intent

## `PUT` Update Cart Payment Intent

```http
https://useast.api.elasticpath.com/v2/carts/:cartID/payments/:payment_intent_id
```

Use this endpoint to update the Stripe payment intent with final cart details whenever there are changes in the cart total.

## Parameters

### Path parameters

| Name      | Required | Type     | Description                                |
|:----------|:---------|:---------|:-------------------------------------------|
| `cartID` | Required | `string` | The universally unique identifier of the cart for which you want to update a payment intent. |
| `payment_intent_id` |  Required | `string` | The universally unique identifier of the payment intent that you want to be updated. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Body

| Name                      | Required | Type      | Description               |
|:--------------------------|:---------|:----------|:--------------------------|
| `gateway` | Required | `string` | Specifies the gateway. You must use `elastic_path_payments_stripe` as the required gateway. |
|`method` | Required | `string` | Specifies the transaction method, such as `purchase` or `authorize`. |
| `options` | Optional | `object` | Defines various Stripe options, such as `automatic_payment_methods` and `receipt_email`, when creating a Payment Intent for a cart. Refer to [Stripe Documentation](https://stripe.com/docs/api/payment_intents) for additional available `options`. |
|  `options.receipt_email`   | Optional | `string`  | Indicates the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode. |
| `options.metadata` | Optional | `object`| Represents a set of key-value pairs that can be linked to an object, providing a convenient way to store additional structured information about the object. See [Stripe Documentation](https://stripe.com/docs/api/payment_intents/update#update_payment_intent-metadata). |

## Request Example

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/carts/:cartID/payments/:payment_intent_id \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
        "data": {
          "gateway": "elastic_path_payments_stripe",
          "method": "authorize",
          "options": {
            "receipt_email": "john@example.com",
            "metadata" : { 
              "updated-key" : "updated-value"
            }
          }
      }
    }
```

## Response Example

```json
{
    "data": {
        "id": "12345",
        "name": "Cart",
        "description": "",
        "type": "cart",
        "discount_settings": {
            "custom_discounts_enabled": false
        },
        "links": {
            "self": "https://useast.api.elasticpath.com/v2/carts/12345"
        },
        "meta": {
            "display_price": {
                "with_tax": {
                    "amount": 20000,
                    "currency": "CAD",
                    "formatted": "$200.00"
                },
                "without_tax": {
                    "amount": 20000,
                    "currency": "CAD",
                    "formatted": "$200.00"
                },
                "tax": {
                    "amount": 0,
                    "currency": "CAD",
                    "formatted": "$0.00"
                },
                "discount": {
                    "amount": 0,
                    "currency": "CAD",
                    "formatted": "$0.00"
                },
                "without_discount": {
                    "amount": 20000,
                    "currency": "CAD",
                    "formatted": "$200.00"
                },
                "shipping": {
                    "amount": 0,
                    "currency": "CAD",
                    "formatted": "$0.00"
                }
            },
            "timestamps": {
                "created_at": "2024-01-16T21:14:58Z",
                "updated_at": "2024-01-16T21:15:03Z",
                "expires_at": "2024-01-23T21:15:03Z"
            }
        },
        "relationships": {
            "items": {
                "data": [
                    {
                        "type": "custom_item",
                        "id": "c1cb7887-28b4-4e30-88b4-647dfce177bf"
                    },
                    {
                        "type": "promotion_item",
                        "id": "6e3cd3be-2f5c-47a0-8f0b-b2fbab4f3a3b"
                    }
                ]
            },
            "customers": {},
            "accounts": {}
        },
        "payment_intent_id": "pi_XXXXXXXX"
    },
    "meta": {
        "payment_intent": {
            "payment_intent": {
                "amount": 20000,
                "amount_capturable": 0,
                "amount_details": {
                    "tip": {
                        "amount": 0
                    }
                },
                "amount_received": 0,
                "application": {
                    "deleted": false,
                    "id": "XXXXXXXX",
                    "name": "",
                    "object": ""
                },
                "application_fee_amount": 0,
                "automatic_payment_methods": null,
                "canceled_at": 0,
                "cancellation_reason": "",
                "capture_method": "automatic",
                "charges": {
                    "data": [],
                    "has_more": false,
                    "total_count": 0,
                    "url": "/v1/charges?payment_intent=pi_XXXXXXXX"
                },
                "client_secret": "pi_XXXXXXXX",
                "confirmation_method": "automatic",
                "created": 1705439701,
                "currency": "cad",
                "customer": null,
                "description": "",
                "id": "pi_XXXXXXXX",
                "invoice": null,
                "last_payment_error": null,
                "livemode": false,
                "metadata": {
                    "updated-key": "updated-value"
                },
                "next_action": null,
                "object": "payment_intent",
                "on_behalf_of": null,
                "payment_method": null,
                "payment_method_options": {
                    "acss_debit": null,
                    "affirm": null,
                    "afterpay_clearpay": null,
                    "alipay": null,
                    "au_becs_debit": null,
                    "bacs_debit": null,
                    "bancontact": null,
                    "blik": null,
                    "boleto": null,
                    "card": {
                        "capture_method": "",
                        "installments": null,
                        "mandate_options": null,
                        "network": "",
                        "request_three_d_secure": "automatic",
                        "setup_future_usage": "",
                        "statement_descriptor_suffix_kana": "",
                        "statement_descriptor_suffix_kanji": ""
                    },
                    "card_present": null,
                    "customer_balance": null,
                    "eps": null,
                    "fpx": null,
                    "giropay": null,
                    "grabpay": null,
                    "ideal": null,
                    "interac_present": null,
                    "klarna": null,
                    "konbini": null,
                    "link": null,
                    "oxxo": null,
                    "p24": null,
                    "paynow": null,
                    "promptpay": null,
                    "sepa_debit": null,
                    "sofort": null,
                    "us_bank_account": null,
                    "wechat_pay": null
                },
                "payment_method_types": [
                    "card"
                ],
                "processing": null,
                "receipt_email": "email@example.com",
                "review": null,
                "setup_future_usage": "",
                "shipping": null,
                "source": null,
                "statement_descriptor": "",
                "statement_descriptor_suffix": "",
                "status": "requires_payment_method",
                "transfer_data": null,
                "transfer_group": ""
            }
        }
    }
}
```

---

## Account Tags(Account-management)

Use Account Tags to dynamically group shoppers with similar traits and tailor promotions just for them.

## Creating Account Tags

1. Go to **Orders > Accounts**.
2. Go to the **Account Tags** tab.
3. Click **New account tag**.
4. Fill in the required Tag Name and optionally the Description.
5. Click **Save** to create the Account Tag.

## Edit Account Tag

1. Go to **Orders > Accounts**.
2. Go to the **Account Tags** tab.
3. Click on the Account Tag from the list to edit or click on the **⋮** icon and click **Edit**.
4. Edit the desired fields.
5. Click **Save** to save the changes.

## Search by Account Tag Name

1. Go to **Orders > Accounts**.
2. Go to the **Account Tags** tab.
3. Enter the search keywords in the search box and then hit the `Enter` key.

## Delete Account Tag

1. Go to **Orders > Accounts**.
2. Go to the **Account Tags** tab.
3. Check the checkbox of the target Account Tag(s). You can multi select or select all from the first checkbox.
4. Click **Delete selected** to delete the selected Account Tags. You can **Clear selection** to unselect.

## Associating Account Tags to Account(s)

1. Go to **Orders > Accounts**.
2. Check the checkbox of the target Account(s)
3. Click **Add account tags** located above the list. The **Bulk add account tags** dialog will show up.
4. In the dialog, click **Add** and select the desired Account Tag(s). You can also search for Account Tag.
  - **Create new tag** will take you to create Account Tag view. After creating the new tag, you can come back to assign the tags.
5. Click **Add tags**.

## View Associated Accounts

1. Go to **Orders > Accounts**.
2. Go to the **Account Tags** tab.
3. Click on the one of the Account Tags.
4. On the Edit view, you can see **Number of associated accounts**.
5. Click on **View accounts** will redirect you to the Accounts list page showing the associated accounts.

## Remove Associated Account Tags

1. Go to **Orders > Accounts**.
2. Check the checkbox of the target Account(s)
3. Click **Remove account tags** located above the list. The **Bulk remove account tags** dialog will show up.
4. In the dialog, click **Add** and select the desired Account Tag(s). You can also search for Account Tag.
5. Click **Remove tags**.

---

## Managing Accounts

import Video from "/src/components/CardDisplay/video"

In an Elastic Path Commerce Cloud store, sellers can create accounts using Commerce Manager and view the purchase history and the addresses associated with an account. To update the membership limit, see [Updating Account Membership Settings](/docs/commerce-manager/settings/general-settings#updating-address-form-settings).

<Video
      mediaSrc="https://www.youtube.com/embed/IqAiqg-d--Y"
      mediaType="embed"
      title="Account Management in Commerce Manager"
      float={"right"}
      size={"400px"}
/>

## Creating Accounts

1. Go to **Orders > Accounts**.
1. Click **Add Account**.
1. In the **Company Name** field, enter a name for the account.
1. In the **Company Legal name** field, enter a legal name of the account.
1. (Optional) In the **Registration ID** field, enter a unique registration ID for the account.
1. Click **Save**.

## Searching Accounts

1. Go to **Orders > Accounts**.
1. Go to the **Accounts** tab.
1. Select one of the following options to search accounts using:
    - **Name**
    - **Legal Name**
    - **Registration ID**
    - **External Reference**
1. Select one of the following search criteria options:
    - **is**
    - **is like**
    - **ends with**
    - **starts with**
1. Enter the desired value in the **Find user** field.
1. Select **Search**.

## Searching Account Users

1. Go to **Orders > Accounts**.
1. Go to the **Users** tab.
1. Choose either **Name** or **Email**.
1. Select one of the following options:
    - **is**
    - **is like**
    - **ends with**
    - **starts with**
1. Enter the desired value in the **Find user** field.
1. Select **Search**.

## Viewing Account Details

1. Go to **Orders > Accounts**.
    All accounts in the store are displayed.
1. To view details of an account, click the account name in the list.

    Account overview, account members associated with the account, purchase history of the account, and the addresses associated with the account are displayed in corresponding tabs.

### Viewing account members associated with an account

1. Go to **Orders > Accounts**.

    All accounts in the store are displayed.
1. Click the account name in the list.
1. On the account details page, click the **Account Members** tab.

    The **Name** and **Email** address of the account members are displayed.

### Adding account members to an account

1. Go to **Orders > Accounts**.

    All accounts in the store are displayed.
1. Click the account name in the list.
1. In the account details page, click the **Account Members** tab.
1. (Optional) To add a new account member to the system, click **Create Account Member**
1. Enter the following information:

    - **Name**: The name of the account member.
    - **Email**: The email of the account member.

1. Click **Save**.
1. (Optional) In the **Account Members** tab, search for the name of the account member in the search bar.

### Viewing purchase history of an account

1. Go to **Orders > Accounts**.

    All accounts in the store are displayed.
1. Click the account name in the list.
1. In the account details page, click the **Purchase History** tab.

    The **Purchase History** tab displays the following information about each purchase:

    - **Date** : Specifies the date of the purchase.
    - **Customer** : Specifies the email address of the customer who made the purchase on behalf of the account.
    - **Items** : Specifies the number of items purchased.
    - **Total** : Specifies the total amount of the purchase.
    - **Payment** : Specifies the status of the payment for the purchase, such as **unpaid**, **authorized**, **paid**, or **refunded**.
    - **Shipping** : Specifies the status of the shipment of the purchase, such as **fulfilled** or **unfulfilled**.
    - **Status** : Specifies the status of the order, such as **incomplete** or **complete**.

    When you click a listing in the purchase history, the **View order** page is displayed. You can manage the orders by updating details, such as, shipping address, shipping status, and payment status. See [Orders](/docs/commerce-manager/orders/orders-cm).

### Viewing addresses associated with an account

1. Go to **Orders > Accounts**.

    All accounts in the store are displayed.
1. Click the account name in the list.
1. In the account details page, click the **Address Book** tab.

    A list of names in each address are displayed.

### Filtering addresses in the Address Book

1. In the **Address Book** tab, select **Add Filter**.

    A list of available filter fields is displayed, including **First Name**, **Last Name**, **Name**, **Company Name**, **Phone Number**, **Address Line 1**, **Address Line 2**, **City**, **County**, **Region**, **Postcode**, **Country**, and **Instructions**.
1. Choose a field and enter the desired value.
1. (Optional) Add additional filters to further narrow the list of addresses.
1. To remove all filters and view the full list again, select **Clear all**.

## Adding Addresses to an Account

1. Go to **Orders > Accounts**.

    All accounts in the store are displayed.
1. Click the account name in the list.
1. In the account details page, click the **Address Book** tab.
1. To add a new address, click a **Add a new address**.

    The **Add New Address** window is displayed.
1. Enter the following information:

    - (Optional) **Name**: The name with which the address is saved.
    - **First name**: The first name of the recipient on this address.
    - **Last name**: The last name of the recipient on this address.
    - (Optional) **Phone number**: A phone number for the address.
    - (Optional) **Company name**: The company name for the address, if any.
    - **Line 1**: The first line of the address, such as the street address.
    - (Optional) **Line 2**: The second line of the address, such as an apartment or unit number.
    - **Postcode**: The ZIP Code, postcode, or other postal reference numbers for the address.
    - (Optional) **City**: The city for the address.
    - **County**: The province for the address.
    - **Country**: The country for the address.
    - (Optional) **Instructions**: Any delivery instructions for the address.

1. Click **Save**.

## Editing Addresses Associated with an Account

1. Go to **Orders > Accounts**.

    All accounts in the store are displayed.
1. Click the account name in the list.
1. In the account details page, click the **Address Book** tab.

    A list of names in each address are displayed.
1. To edit the details of an address, do one of the following:

      - Click a name.
      - In the address list, click the **...** icon next to the address name and click **Edit**.

      The **Edit Address** window is displayed.

1. Update the details as required.
1. Click **Save**.

## Deleting Addresses Associated with an Account

1. Go to **Orders > Accounts**.

    All accounts in the store are displayed.
1. Click the account name in the list.
1. In the account details page, click the **Address Book** tab.

    A list of names in each address are displayed.
1. To delete an address, click the **...** icon next to the address name and click **Delete**.

## Deleting Accounts

1. Go to **Orders > Accounts**.

    All accounts in the store are displayed.
1. Click the **...** icon next to the account name in the list and click **Delete**.

## Demo

---

## Order Insights

The **Order Insights** dashboard provides powerful analytics to help you understand your store's performance and make data-driven decisions. Using Order Insights enables you to answer questions such as:

- What was the total number of orders in a given time period?
- What was the total revenue generated?
- How much discount was applied?
- What are the trends in order volume and revenue over time?

This is important because it helps you track your business performance, identify trends, and optimize your operations.

## Accessing Order Insights

1. Go to **Orders > Insights** in Commerce Manager.
2. The Order Insights dashboard displays with default filters applied.

## Filtering Data

You can filter the data displayed in the dashboard using the following options:

### Order Date Range

1. Click the **Order date range** dropdown.
2. Select a predefined range or choose custom start and end dates.
3. The dashboard compares the selected period with the previous period of equal length.

### Currency

1. If your store uses multiple currencies, click the **Currency** dropdown.
2. Select the currency you want to analyze (e.g., USD, EUR, GBP).

### Additional Filters

Click **+ Add Filter** to add more filtering criteria to narrow down your data analysis.

* Filter by Product – metrics reflect only orders that contain the selected product:
  - Revenue: Sum of order totals for those orders (in the selected currency).
  - Discounts: Sum of all discounts applied to those orders.
  - Orders: Count of orders that include the product.
* Filter by Promotion – metrics reflect only orders that used the selected promotion:
  - Revenue: Sum of order totals for those orders (in the selected currency).
  - Discounts: Sum of all discounts applied to those orders.
  - Orders: Count of orders that used the promotion.

## Understanding the Metrics

The dashboard displays three key performance indicators:

### Total Orders

Shows the total number of orders placed during the selected time period, with a percentage comparison to the previous period.

- **Green percentage (↑)**: Indicates an increase compared to the previous period
- **Red percentage (↓)**: Indicates a decrease compared to the previous period

### Total Revenue

Displays the total revenue generated during the selected time period, with a percentage comparison to the previous period.

### Total Discounts

Shows the total value of discounts applied to orders during the selected time period, with a percentage comparison to the previous period.

## Trend Charts

The dashboard includes two interactive trend charts:

### Total Orders Trend

Visualizes the number of orders over time. You can toggle between different time intervals using the dropdown (Hourly, Daily, Weekly).

- **Solid line**: Current period data
- **Dotted line**: Previous period comparison

### Total Order Value Trend

Visualizes the revenue generated over time. You can toggle between different time intervals using the dropdown (Hourly, Daily, Weekly).

- **Solid line**: Current period data
- **Dotted line**: Previous period comparison

## Tips for Using Order Insights

- Hover over any point on the charts to see detailed information for that specific time point.
- Use date range comparisons to identify growth trends or areas needing attention.
- Monitor the discount percentage to ensure promotional strategies are sustainable.
- Compare current performance against previous periods to measure the impact of marketing campaigns or seasonal changes.

## Demo
import Video from "/src/components/CardDisplay/video"

<Video
  mediaSrc="https://share.vidyard.com/watch/oQD1xA9fPJUDYTdwFQQ3BL"
  mediaType="embed"
  title="Order Insights Dashboard Overview"
  description="Order Insights Dashboard Overview"
/>

---

## Creating an Application Key

In a Commerce store, all organization and store admins can create, view, and manage the list of keys in a store.

1. In Commerce Manager, go to **Settings > API Keys**.

    The **Application Keys** Page is displayed.
1. Go to the **Application Keys** tab.
1. Click **Create new**.

    The **New Application Key** page is displayed.
1. In the **Name** field, enter the name of the key that you want.
1. (Optional) In the **Requests per second** field, enter the reserved rate limit for the key. Each organization and store has a specific rate limit. You can reserve a rate limit to the application key associated with that specific application. For more information, see [Application Keys Overview](/docs/api/application-keys/application-keys-introduction).
1. Click **Create**.

    Make sure to copy your **Client Secret** key and save it somewhere else because your **Client Secret** key will be not be displayed to you again. Alternatively, you can click **Download as CSV File** to save the information.

    The **Store ID**, **Requests per second**, **API Base URL**, **Client ID**, and **Client-Secret** fields are populated. The application key is created and shown on the **Application Keys** page.

1. (Optional) To delete the application key, do the following:
    1. In the **Actions** column, click the three dots.
    1. Click **Delete**.
    1. Enter the name of the application Key to be deleted.
    1. Click **Yes, Delete**. This action cannot be undone.

---

## Authentication Management

The Authentication Management tab is used to configure one or more single sign-on authentication providers. Single sign-on is used to verify a user’s identity using the OpenID Connect protocol, without saving user information such as a password.

:::caution
Changing these settings affects how customers authenticate with your store. Any misconfiguration might prevent users from authenticating.
:::

For more information, see [Single sign-on and authentication](/docs/api/single-sign-on) and [Single sign-on with OpenID Connect](/guides/How-To/Authentication/get-single-sign-on-account-management-token).

:::caution
To set up single sign-on for customers of your store, use the **Buyer Organization** realm. To set up single sign-on for store administrators and developers, use the **Merchant Organization** realm.
:::

## Merchant Organization

To log into the correct store’s Commerce Manager as a developer or administrator when using single sign-on, you must:

- set a *URL prefix* for your store’s Merchant Organization realm.
- Add an OpenID provider

:::note
This prefix must be unique, and comprised of between two and 24 alphanumeric characters.
:::

1. On the **Settings > Authentication** tab, click **Merchant Organization** realm.

1. In the **Edit Configuration** area for the realm, enter your URL prefix.

   You enter the URL prefix every time you log in to Commerce Manager.

1. Click **Save** to save the configuration.
1. Select **+ Add New Provider**.
1. Provide the following information.

     | Option | Required | Description                                                                                                                                                                   |
     | --- | --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
     | **Name** | Required | A name for your OpenID provider. This is the name displayed to shoppers in your storefront.                                                                                   |
     | **Discovery URL** | Required | The URL where the OpenID Connect authentication configuration is found. This is often the URL of the provider. For example: `https://<URL>/.well-known/openid-configuration`. |
     | **Client ID** | Required | The client identifier that Composable Commerce uses to identify itself with the authentication provider.                                                                      |
     | **Client Secret** | Required | A secret code known only to Composable Commerce and the authentication provider.                                                                                              |
1. Click **Save** to save the configuration.

After you have properly configured one or more authentication providers, when customers open the **Login** dialog box, a **Login with [provider]** button is available for single sign-on authentication workflow.

## Account Management Realm

You can use the **Account Management Realm** to configure single sign-on and Open ID Connect providers for your accounts and account members in your Commerce stores. This allows shoppers with Commerce accounts to access multiple applications and services with a single set of credentials, streamlining the login process and reducing the need for multiple usernames and passwords.

When configuring single sign-on in **Account Management Realm**, do the following:

- (required) provide the client redirect URIs. These tell Commerce which URI a shopper should be redirected to when authentication completes.
- (required) add the Open ID provider through which shoppers will authenticate.
- (optional) Provide a password profile for your Open ID providers.
- (required) Configure the **Account Authentication Settings**.

The steps below describe how to configure accounts and account members to use single sign-on.

1. Go to **Settings > Authentication**.
1. Select **Account Management Realm**.
1. In **Client Redirect URIs**, enter all the client redirect URIs. These are the pages on your storefront where you want shoppers with accounts to be able to sign in to an Open ID provider.
1. In **OpenID Providers**, select **+ Add New Provider**.
1. Provide the following information.

    | Option | Required | Description                                                                                                                                                                     |
    | --- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Name** | Required | A name for your OpenID provider. This is the name displayed to shoppers in your storefront.                                                                                     |
    | **Discovery URL** | Required | The URL where the OpenID Connect authentication configuration is found. This is often at the URL of the provider. For example: `https://<URL>/.well-known/openid-configuration` |
    | **Client ID** | Required | The client identifier that Composable Commerce uses to identify itself with the authentication provider.                                                                        |
    | **Client Secret** | Required | A secret code known only to Composable Commerce and the authentication provider.                                                                                                                                                                                |
1. Click **Save** to save the configuration.
1. In **Password Profiles**, select **+ Add New Password Profile**.
1. Provide the following information.

    | Option          | Required | Description                                                                                                          |
    |-----------------| --- |----------------------------------------------------------------------------------------------------------------------|
    | **Name**            | Required | A name for your password profile.                                                                                    |
    | **Username format** | Required | The username format required by the system or application where the usernames are used. Either **Email** or **Any**. |

1. In **Account Authentication Settings**, configure the following settings:

    - Turn on the **Enable Self-Signup** toggle if your application or service allows shoppers to sign up by completing a registration form, if they are not already registered.
    - Turn on the **Enable Auto Create Account for Account Members** toggle if you want to automatically create an account for a shopper who is signing in but does not yet have an account.
    - Turn on the **Enable Account Member Self Management** if you wish to allow shoppers to automatically create their accounts in Commerce by completing a registration form, if they do not already have accounts.

After you have properly configured one or more authentication providers, when customers open the **Login** dialog box, a **Login with [provider]** button is available for single sign-on authentication workflow.

## Buyer Organization

When the storefront begins the single sign-on flow for an end user or customer, it must tell Commerce which URI the user should be redirected to when the authentication completes. This is the `redirect_uri` parameter discussed in [Single sign-on with OpenID Connect](/docs/customer-management/customer-management-api/customer-tokens). These URLs must be explicitly listed as *Redirect URIs* to prevent phishing and other security vulnerabilities.

1. On the **Settings > Authentication**, click **Buyer Organization** realm.

1. In the **Edit Configuration** area for the realm, enter redirect URIs.

   You can view the list of redirect URIs as tags or as a comma-separated list.

1. Click **Save** to save the configuration.
1. In **OpenID Providers**, select **+ Add New Provider**.
1. Provide the following information.

   | Option | Required | Description                                                                                                                                                                     |
   | --- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   | **Name** | Required | A name for your OpenID provider. This is the name displayed to shoppers in your storefront.                                                                                     |
   | **Discovery URL** | Required | The URL where the OpenID Connect authentication configuration is found. This is often at the URL of the provider. For example: `https://<URL>/.well-known/openid-configuration` |
   | **Client ID** | Required | The client identifier that Composable Commerce uses to identify itself with the authentication provider.                                                                        |
   | **Client Secret** | Required | A secret code known only to Composable Commerce and the authentication provider.                                                                                                                                                                                |
1. Click **Save** to save the configuration.

After you have properly configured one or more authentication providers, when customers open the **Login** dialog box, a **Login with [provider]** button is available for single sign-on authentication workflow.

---

## Cart Preview

**BETA** Cart Preview is currently in beta and allows you to simulate real-world cart scenarios for validating catalog setups, pricing, and promotion evaluations.

## Overview

Cart Preview in Commerce Manager helps teams test and validate how catalogs, pricing, and promotions will behave in a live cart environment before deploying changes to production.

## Key Features

- **Catalog Validation**: Validate how your catalog structure and product configurations will appear in customer carts
- **Pricing Simulation**: Test pricing rules and calculations
- **Promotion Evaluation**: Validate promotion logic and ensure discounts apply correctly

## Accessing Cart Preview

1. Navigate to **Merchandise** > **Cart Preview**.
2. Configure the shopper context (optional):
   - Set the catalog **Channel** and **Context tag** for specific products and pricing
   - Select the **Currency**
   - Set the **Shop Date** to test future promotions
3. Click **Add products** to view available products based on your shopper context.
4. Select the checkbox next to each product you want to add to the cart.
5. Click **Add selected** to add the chosen products to your cart.

### Simulation Settings

- **Channel and Context Tag**: These can be found in your Catalog Rules. This determines what products and prices will be visible to the shopper.  For more information, please see [Catalog Rules](/docs/commerce-manager/product-experience-manager/catalogs/catalog-rules).
- **Currency**: of the store you want to simulate
- **Shop Date**: This date is only relevant for testing out a promotion from Promotion Builder.

If none of these are set, then the products, pricing will be relevant for all shoppers. Using the settings above will help you test out a segment of shoppers

:::note
Cart Preview is a beta feature. If you encounter any issues or have feedback, please contact support.
:::

### API Documentation
[Cart Preview API](/docs/api/carts/create-a-cart#preview-cart)

## Demos

import Video from "/src/components/CardDisplay/video"

<Video
  mediaSrc="https://share.vidyard.com/watch/bzoE8H33zGspaqT7CZ8J5i"
  mediaType="embed"
  title="Cart Preview" />

---

## Commerce Extensions

## Creating Custom APIs

1. Go to **Extensions > Custom APIs**.
1. Select **Create New**.
1. In the **Basic Details** section:
    1. **Name**: Enter the the name of the Custom API. It must be between 1 and 255 characters.
    1. **Description**: Provide a description for the Custom API.
1. In the **Advanced Options** section:
    1. **API Type**: Specify the type of the Custom API.
    1. **Slug**: Enter a unique slug identifier for the Custom API.
    1. (Optional) In **Settings**, select the checkbox for **Allow UPSERT** so the system can automatically create a new record if it doesn't exist when updating. For more details, see [Upsert Custom API Entries](/guides/How-To/commerce-extensions/create-a-multilocation-inventories-resource#upsert-custom-api-entries).
1. Select **Create Custom API**.

## Custom API Navigation Placement
Users can now configure where Custom APIs appear in the Commerce Manager navigation sidebar.

1. Edit an existing Custom API.
1. In the **Navigation** section, configure where the Custom API appears in the Commerce Manager navigation sidebar:
    1. **Main Section**: Select the main navigation section where the Custom API should appear (Home, Merchandise, Orders, Subscriptions, Composer, Extensions, or Settings).
    1. **Sub-section**: Optionally select a specific sub-section to nest the Custom API under (e.g., Products within Merchandise).

![Custom API Navigation](/assets/CustomAPI_navigation.png)

<grid class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-6">
  <CardDisplay
    mediaSrc="https://share.vidyard.com/watch/WEduH3nK7FFYYdy2tXHe7f"
    mediaType="embed"
    title="Custom API Navigation Placement"
    description="Custom API Navigation Placement in Commerce Manager"
  />
</grid>

## Creating Custom Fields

To create a Custom Field for a Custom API, follow these steps:

1. Go to **Extensions > Custom APIs**.
1. Select **Create Field** and choose one of these field types:
    - **String**
    - **Integer**
    - **Boolean**
    - **Float**
    - **Any**
    - **List**
1. In the **Basic Details** section:
    1. **Name**: Enter the field name. It must be between 1 and 255 characters.
    1. **Description**: Provide a description for the field.
    1. **Slug**: Enter a unique slug identifier for the field.
1. (Optional) In **Settings** section, select the checkbox for **Use as the URL of entry record**. This option is shown only when you select **String** field type. When this option is enabled, the value of this field will be used as the URL slug for entries created in the Custom API. This field must be a String, unique, and cannot allow null value. The Custom API must not have any existing entries.
1. (Optional) In **Settings** section, set **Sort Order** of your field. This option allows you to prioritize the order in which fields are presented in the user interface. Fields with a higher value will appear first. The value must be between 0 and 1000.
1. In the **Validation** section:
    1. Set the value rules from the drop-down lists:
        - **Can be NULL** or **Cannot be NULL**.  This option is disabled when you select **Use as the URL of entry record**.
        - **Can be changed** or **Cannot be changed**
        - For **String** fields, choose among **Is unique and case sensitive**, **Does not need to be unique**, or **Is unique and case insensitive**.
            The **Does not need to be unique** option is disabled when you select **Use as the URL of entry record**.
    1. (For **String** fields) Under **Character Limit**, enter **Minimum Length** and **Maximum Length**.
    1. (For **Integer** and **Float** fields) Under **Input Range**, enter **Minimum Value** and **Maximum Value**.
    1. (For **String** fields) In the **Regular Expression** field, enter a less than 1024 character RE2 regular expression to restrict the specific characters that can be stored.

1. Select **Create Field**.

## Creating Custom API Entries

To create a Custom API Entry for a Custom API, follow these steps:

1. Go to **Extensions > Custom APIs**.
1. In the **Actions** column, click the button associated with the target Custom API and click **View Entries** option.
1. Select **Create Entry**.
1. Fill out the values for the configured Custom Fields as desired.
1. Select **Create Entry**.

## Manage Custom API role permissions

Manage Custom API access by assigning permissions for each role.

1. Go to **Extensions > Custom APIs**.
1. Edit the target Custom API.
1. Click **Roles and Access** tab.
1. Click **New role permissions** and select the target roles.
1. Check the checkboxes of the permissions you want to grant to the selected roles.
1. Click **Save Roles and Access** at the top right of the screen to save all changes.
1. You can delete any unwanted role permission.

NOTE: **Seller Admins** have full permissions by default, and this cannot be modified.

## Access OpenAPI Spec

1. Go to **Extensions > Custom APIs**.
1. In the top right corner, click `OpenAPI specs` dropdown.
1. Select `View OpenAPI spec` to view the OpenAPI spec in-app.
1. Select `Download OpenAPI spec` to download the OpenAPI spec.

![OpenAPI Spec](/assets/CM_OpenAPI.png)

### Demo Videos
import CardDisplay from "/src/components/CardDisplay";

<grid class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-6">
  <CardDisplay
    mediaSrc="https://share.vidyard.com/watch/rqsBpMfftBwTxjoDNeJL7F?"
    mediaType="embed"
    title=""
    description="Managing Role Policies for Custom APIs in Commerce Manager"
  />
  <CardDisplay
    mediaSrc="https://share.vidyard.com/watch/PBVdCPKA3ECjxjjrLopdHp?"
    mediaType="embed"
    title=""
    description="Custom API Role Policies for Enhanced Access Control"
  />
</grid>

---

## Managing Customers

import Video from "/src/components/CardDisplay/video"

In Commerce Manager, go to **Orders > Customer** to manage customers.

For a conceptual overview of customers in Composable Commerce, see [Customers](/docs/customer-management/customers).

## Searching Customers

To search customers, do the following:

1. Choose either **Name** or **Email**.
1. Select one of the following options:
    - **is**
    - **is like**
    - **ends with**
    - **starts with**
1. Enter the desired value in the **Find customer** field.
1. Click **Search**.

## Creating Customers

1. Click **New Customer** to create a new customer.
1. In the **Basic Information** section, enter the following details:
    - **Name**
    - **Customer Email**
    - **Password**
    - **External Reference**, if any.
1. Click **Save**.

## Editing Customers

You can add one or more addresses to the customer details or modify their basic information.

1. Select the customer from the list.
1. Modify the **Name**, **Customer Email**, **Password**, or **External Reference** if required.
1. Modify the **Custom Fields** section if required.
1. Click **Add a new Address**.
1. Enter the details of the customer address, add any instructions, and then click **Save**.
1. Click **Save**.

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/iE5VpO4GS1k"
  mediaType="embed"
  title="Extend a Customer Resource using Flows" />

---

## Creating Flows

import Video from "/src/components/CardDisplay/video"

With flows, you can extend an existing resource or create a new resource for your store or organization. You can also use to create simple custom fields for existing resources or complex collections of fields and data. You can create useful resources for your customers, such as a want list, or blogs for your store or organization.

For more information about using flows in Commerce, see [Custom Data (Flows)](/docs/commerce-manager/flows/).

:::caution
Do not create flows in **Extensions** > **Flows**. Use [**Merchandise > Products > Templates**](/docs/commerce-manager/product-experience-manager/extending-products/templates) page to create a Product Experience Manager flow. However, all flows in the store are displayed in the **Extensions** > **Flows** page where the template flows are labelled with a prefix `PCM`. We recommend not to update template flows in this page.
:::

## Creating Flows

1. Go to **Extensions > Flows**.

    All flows available in the store are displayed, if any.
1. Click **New flow**.

    The **Create New Flow** window is displayed.
1. In the **Name** field, enter a name for the flow.
1. In the **Slug** field, enter a slug.

    By default, the name is used as the slug.
1. In the **Description** field, enter a description for the flow.
1. To enable the flow, select **Enabled**.
1. Click **Save**.

    The new flow is added to the list of flows available in the store. All flows are displayed under **Extensions > Flows** from the menu.

:::note
- Core flows will be labelled as `CORE`. Refer to [Flows in Commerce](/docs/api/flows/flows#flows-in-commerce) for more details.
:::

### Adding fields to a flow

1. To add field to a flow, in the **Flows** page, select the flow.

    A window with the details of the flow is displayed.
1. Click **+New Field**.
1. In **Field Type**, select one of the following:

    - **Boolean**
    - **Float**
    - **Integer**
    - **String**
    - **Date**
    - **Relationship**
    A relationship type specifies the relationship between the flow and a Composable Commerce resource, such as products. You can have several relationships in a flow.

1. Enter the following common settings:

    - **Name**: Specifies the name of the field.
    - **Slug**: Specifies a unique slug identifier for the field.
    - **Description**: Specifies a description for this field.
    - **Required Field**: Specifies whether the field is required. Choose **Yes** or **No**. Select **No** if the **Field Type** is **Relationship**.
    - **Default Value**: Specifies a default value for the field if no value is provided and the field is required.
    - **Order**: Specifies the order in which this field is returned relative to the rest of the flow fields. Use a number.

1. In the **Validation** field, enter the valid input options for the field:

    | Field type | Validation description |
    | :------------- | :------------- |
    | **Boolean** | No validation required. |
    | **Float**,  | Enter a range of valid values. Optionally, you can add a list of valid values. |
    | **Integer** | Enter a range of valid integer values. Optionally, you can add a list of valid values. |
    | **String** | Select a valid value for the field, such as **email**, **slug**, or **uuid**, or enter a list of valid string options. |
    | **Date** | Enter a date that matches the standard date format described previously. You can also list valid dates. |
    | **Relationship** | Select **One to One** as the relationship type, and select the **Resource**. The **Resource** can be one of **Products**, **Brands**, **Collections**, **Categories**, **Customers**, **Orders**, or **Promotions** resources. |

1. Click **Save**.

You can delete a field by clicking the delete icon in the field listing.

### Adding values to fields

1. In the sidebar menu, go to **Flows** and click the flow name.

All field names in the flow are displayed.

1. Click **New Entry** and enter values for the fields as required.

:::caution
You cannot add attributes for template flows in this page. Use the [**Product Experience Manager > Configurations > Attributes**](/docs/commerce-manager/product-experience-manager/extending-products/templates#attributes) page to add attributes in a Product Experience Manager template.
:::

## Updating Flow Settings

1. Go to **Extensions > Flows**.
1. To edit a flow, click the flow.
1. In the **Fields** window, click **Flow Settings**.
1. In the **Flow Settings** window, update the settings as required.
1. Click **Save**.

## Deleting Flows

1. Go to **Extensions > Flows**.
1. To delete a flow, click the flow.
1. In the **Fields** window, click **Delete Flow**.
1. When prompted to confirm the delete action, click **Delete**.

## Sorting and Filtering Flows

You can sort the flow list by **Name**, **Slug**, **Description** or **Status**.

You can filter the list to show only **Enabled** or **Disabled** flows.

## Demos

- <Video
  mediaSrc="https://www.youtube.com/embed/uPe5WE0W5pU"
  mediaType="embed"
  title="Creating a Custom Flow" />

---

## Commerce Manager Overview

import Video from "/src/components/CardDisplay/video"

Commerce Manager is a web-based user interface to manage your store. In Commerce Manager, a user depending on their role within the store can do some or all of the following:

- Create, edit, and delete products.
- Set product status as live or draft.
- Create and manage child products using variations, modifiers, and options.
- Manage product inventory.
- Manage orders.
- Create, edit, and delete customers.
- Manage files.
- Create, edit, and delete flows and fields.
- Create and manage promotions and promotion codes.
- Change site settings, including currency, payment gateways, and other integrations.
- Manage authentication.
- Create a new store.
- Manage teams.

You can have one or more stores associated with your account.

## Home Page

The Commerce Manager **Home** page provides an option to invite team members to work in your store and to view the API keys for your store.

### Inviting Team Members

Store administrators can invite team members to work on the store configuration. The team member can access the store through Commerce Manager and the API. All team members with the login credentials can log in to Commerce Manager and go to **System > Application Keys** to get their API keys.

A store admin can also invite team members from the **System > Store Settings > Team Management** page.

1. On the **Home** page, enter the email address of the team member you want to invite.
1. Select a role for the team member.

    For more information, see [Roles](/guides/Getting-Started/team-management).

As a store admin, you can revoke access of a team member at any time without changing the settings for other team members. For example, you can revoke access of an external developer working on the store when the contract ends without revoking access of other members in the team.

A store admin can invite registered or unregistered users using their email address. For an unregistered user, the invitation includes a link to the registration form.

### Selecting a Store

1. Log into Commerce Manager.
1. Click your profile icon at the top-right corner.
1. In the drop-down menu, click **Stores**.

    All stores associated with your account are listed.
1. Select the store.

    The store **Home** page opens.
1. Optionally, invite your colleagues to collaborate.

    For more information, see [Team Management](/guides/Getting-Started/team-management) section.

:::caution
If you are logged on to Commerce Manager using single sign-on, Your profile information is provided by the single sign-on provider. You cannot create new stores, invite users, or edit your profile information.

Invites sent to non-registered users are valid only for 36 hours, after which the link expires and a new invite must be created.
:::

## Related Resources

For Commerce Manager course in the learning center, see [Commerce Administrator](https://learn.elasticpath.com/learn/learning_plan/view/1/elastic-path-commerce-cloud-functional-administrator). You must log in to access the course.

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/yz7uZ3GKjLc"
  mediaType="embed"
  title="Getting Started with the Commerce Manager" />

---

## Integrations(Integrations)

You can view your store’s integrations on the **SETTINGS > Webhooks**.

For an overview of how integrations work in Commerce, see [Integrations](/docs/api/integrations/integrations-introduction).

## Sorting and filtering integrations

You can sort the integrations list by **Name**, **Description**, or **Status**.

You can filter the integrations list to show which integrations are enabled or disabled.

## Creating a new integration

1. On the **SETTINGS > Webhooks**, select **+New Webhook**.
1. On the **Create New Webhook** page, enter the following information:

     | Section | Fields |
     | :------------- | :------------- |
     | **Webhook details** | **Name** and **Description**. The **Integration type** is fixed at `webhook`.|
     | **Configuration** | **URL** for the integration, and **Secret key**. The secret key is forwarded along with the request as a header. |
     | **Observes** | These events can trigger webhooks. Select the ones you want to trigger the webhook: **Created**, **Updated**, or **Deleted** for most objects; **Updated** or **Deleted** for Cart; **Created** or **Deleted** for File; **Created**, **Updated**, **Fulfilled**, **Authorized**, **Paid/Captured**, **Cancelled**, or **Refunded** for Order; **Updated** for Payment Gateway. **Created**, **Updated**, or **Deleted** for customers. Only five events can be added. |
     | **Enabled** | Enable the integration.|

    :::caution
    You cannot edit `aws_sqs` and `stomp` integration types using Commerce Manager. You can edit these integrations using the [update an integration](/docs/api/integrations/update-integration) endpoint.
    :::

---

## Orders(Orders)

import Video from "/src/components/CardDisplay/video"

To view all the orders in the store, log into Commerce Manager and go to **STORE > Orders**. You can manage orders on the **All orders** page.

## Viewing Details of a Specific Order

1. In Commerce Manager, go to **Orders**.
1. On the **All orders** page, do one of the following:

    1. Click an order.

        You can view a product's details by clicking on a product name. This only applies to [products](/docs/commerce-manager/product-experience-manager/products/view-product-details).
    1. Click **Jump to order** and do the following:
        1. In the **Order ID** field, enter the order ID of the order that you want to view.
        1. Click **Search**.

1. (Optional) To quit the current order page and view details of another order:

    1. Click **Jump to another order** and enter the order ID.
    1. Click **Search**.

    You can see the following details of a specific order on the **View order** tab:

    - Order ID
    - External Reference ID, if any
    - Order items
    - Order status
    - Payment status
    - Shipping status
    - Customer details
    - Billing details
    - Shipping details
    - Details of items in the order
    - Order total
    - Order history
    - Custom fields, if any
    - Shipping groups, if any

When an order is associated with one or multiple shipping groups, the following is displayed:

- **Total Shipping Costs** - subtotal, fees, and tax
- **Total** - amount of order items for each shipping group

Additionally, each shipping group shows:

- **Shipping Group ID**
- **Shipping Details**
- **Tracking** information
- **Delivery Instructions**
- **(optional) Custom Fields** - Any custom fields added to the shipping group via flows.

:::note
- If there are any shipping groups associated with an order, the shipping details are displayed under the shipping groups. Otherwise, the shipping details are displayed at the top of the order items details.
:::

## Anonymizing Orders

You can anonymize orders so that the following information about the order are deleted from the system:

- **Customer Details**
- **Shipping Details**
- **Billing Details**

You can anonymize an order when it is fulfilled, canceled, or fully refunded.

You cannot update or access these information about an order after anonymizing the order.

:::caution
For **Elastic Path Payment Powered by Stripe** customers, refer to the [Stripe Documentation](https://support.stripe.com/questions/i-would-like-to-delete-the-information-stripe-has-collected-from-me) to learn more about how anonymization requests are processed if a customer record is created in Stripe.
:::

Do the following to anonymize an order:

1. On the **All orders** page, click the order that you want to anonymize.
1. Click **Anonymize Order**.

    Alternatively, you can select the checkbox for the order, click the ellipses, and then select **Anonymize**. You cannot update the order details of an order after anonymizing the order.

1. (Optional) Select the checkbox for multiple orders, and click **Actions** > **Anonymize** to anonymize the selected orders.

## Refunding an Order

You can refund an order directly through your payment gateway, or using Commerce API or Commerce Manager. See [Refunds](/docs/api/carts/payments#refunds).

On the **View order** tab, you can refund the order directly from Elastic Path Commerce Manager. You can refund partially or the full amount.

1. On the **All orders** page, click an order.
1. On the **View order** tab, click **Refund** in the **View Order History** box.
1. Enter the refund amount.
1. Click **Refund**.

    The payment status of the order is updated to **Refunded**.

Optionally, you can also click **Mark as Refunded** to change the payment status to **Refunded** and then manually process the refund using third-party payment gateways.

## Canceling an Order

You can cancel an unfulfilled order.

1. On the **All orders** page, click an order.
1. On the **View order** tab, click **Cancel Order**.

    A message to confirm the delete action is displayed.
1. Click **Yes, cancel order**.
    The order cancellation message is displayed and the status of the order is updated to **Cancelled**.

Canceling an order does not automatically refund a payment, you must refund the orders manually.

## Updating Shipping Details, Delivery Instructions, and Custom Fields

1. On the **All orders** page, click an order.
1. On the **View order** tab, click the **Edit** icon associated with **Shipping Details** and **Delivery Instructions**.
1. Update the address and delivery instructions as required.
1. Click **Save**.

Depending on the flow configuration for orders, the custom fields are displayed on the **Order details** page. You can enter the required information in these fields. For more information about adding custom fields, see the [Flows](/docs/commerce-manager/flows/) section.

## Updating External Reference ID

1. On the **All orders** page, click an order that is updated with an external reference ID. See [Update an Order](/docs/api/carts/update-an-order).
1. On the **View order** tab, click the **Edit** icon associated with **External Reference ID**.
1. Update the external reference ID for an order as required.

## Filtering Orders

1. On the **All orders** page, click the **Add Filter** button.
1. Select any or all of the following details as required:

    - **Customer name**: Enter the name of a customer to view all orders associated with that customer.
    - **Customer email**: Enter the email address of a customer to view all orders associated with that customer.
    - **Date range**: Enter a date range to view orders during the selected period.
    - **Payment status**: Select a payment status to view all orders with that payment status. You can select **paid**, **unpaid**, **authorized**, **refunded**, **partially_authorized**, or **partially_paid**.
    - **Shipping status**: Select one of the shipping statuses **fulfilled** or **unfulfilled** to view orders with the selected shipping status.
    - **Order status**: Select the order status, such as **complete**, **incomplete**, **cancelled**, or **processing** to view orders with the selected status.
    - **External Reference ID**: Enter an external reference ID for an order. It can contain alphanumeric characters, special characters, and spaces, and does not required to be unique. It can be used to include an external reference from a separate company system.
    - **Order Number**: Enter an Order Number for an order. It can contain alphanumeric characters, special characters, and spaces, and does not need to be unique.
    - **Product SKU**: Enter the SKU of the product to retrieve all orders that has this product. These orders might contain other products too.
    - **Product ID**: Enter the ID of the product to retrieve all orders that has this product. These orders might contain other products too.
    - **Account ID**: Enter the ID of an account to view all orders associated with that account.
    - **Account member ID**: Enter ID of an account member to view all orders associated with that account member.
    - **Customer ID**: Enter the ID of the customer whose orders you want to see.
    - **Billing postcode**: Enter a postcode to view all orders related to a specific billing address with this postcode.
    - **Shipping postcode**: Enter a post code to view all orders to a specific shipping address with this postcode.

1. Click **Apply Filters**.

    The selected filters and the results are displayed. You can remove a filter by clicking **X** next to the filter, or you can reset the filter by clicking **Clear All**.

## Exporting Order Details

You can filter orders as required and export the result in a text file in a comma-separated value (CSV) format.

:::caution
Only seller administrators can export order details.
:::

1. On the **All orders** page, click **Manage Export**.

    The **Manage Exports** window with previous export details, if any, is displayed.
1. In the **Manage Exports** window, click **Create export**.

    After completing the export, the status of the export is updated to **Complete**.
1. To download the report, click **Download**.

## Related Resources

- [Orders API](/docs/api/carts/orders)
- [Shipping Groups](/docs/ship-groups/shipping-groups/index)

### Demos

- <Video
  mediaSrc="https://www.youtube.com/embed/uEI1Cc5yJqI"
  mediaType="embed"
  title="Order Updates in Commerce Manager" />
- <Video
  mediaSrc="https://www.youtube.com/embed/gAk4ny0NZ1Q"
  mediaType="embed"
  title="Shipping Groups" />

---

## Organizations Overview

In Commerce Manager, an Org Admin can manage both organization and stores.

## Home Page

1. Log into Commerce Manager.
1. Select **Organizations** or **Stores** depending on your management requirements.
1. (Optional) If you select **Organizations**, the **Your organizations** page is displayed. From there, select the organization you want to manage.
1. (Optional) If you select **Stores**, the **Your Stores** page is displayed. From there, select the store you want to manage.
1. (Optional) If you want to return to the organization home page after landing in the store within your selected organization, go to your **profile** and click **Go back to Org**.

1. (Optional) To go back to the main page, within your organization, navigate to your **profile** and select **stores**.

## Creating a New Store within an Organization

1. Log into Commerce Manager.
1. Select **Organizations**.

    The **Your organizations** page is displayed.
1. Select organization you want to manage from the list.
1. Under **ORG MANAGEMENT**, go to **Stores**.
1. Click **Create new** at the top-right corner once you land in your selected organization.
1. Enter a name for the store in the **Name** field.
1. Click **Save** or **Save and go to store**.

    A new store with the provided name is created.

## Searching Stores

You can search for a specific store within an organization.

1. Log into Commerce Manager.
1. Select **Organizations**.

    The **Your organizations** page is displayed.
1. On the **Your organizations** page, select organization you want to manage from the list.
1. Under **ORG MANAGEMENT**, go to **Stores**.
1. In the **Search** field, enter name of the store that you want to search.

## Team Management

The Commerce Manager home page provides an option to invite your team members to your organization. You can manage your team members from **SYSTEM > Organization Settings > Team Management** tab.

### Inviting Team Members

1. Click **Invite User** on the **Organization Settings** page. The **User Details** dialog box is displayed.
1. In the **Email** field, enter the email address of the user to be invited.
1. Click **Save**.

### Deleting Team Members

1. In the **Actions** column, on the **Organization Settings** page, click the ellipses associated with the name of the user.
1. Click **Delete** to delete a team member from an organization. This action cannot be undone.

---

## Managing Currencies

In your organizations, you can manage currencies from **SYSTEM > Organization Settings > Currencies** tab.

You can set up any currency as your organization's default currency as long as the currency's **Enabled** and **Default** checkboxes are selected while [creating](#create-a-currency) or [editing](#edit-a-currency) a currency.

:::note
- In Commerce Manager, when you create a new currency in your organization, a store belonging to that organization may not immediately inherit that currency. You might have to click the ellipsis associated with the currency **Code**, select **Edit**, and then click **Save** to see the new organization-level currency. See [Edit a Currency](#edit-a-currency).
- In the API, when an organization creates a new currency or if there is a mismatch between the store currencies and organization currencies, pass an empty request body on a store-level currency using the [Update a Currency](/docs/api/pxm/currencies/update-a-currency) endpoint to invalidate the cache. This will ensure that the store currencies are updated with the new organization currency.
:::

## Create a Currency

1. In Commerce Manager, go to **SETTINGS > Currencies**.
1. Click **New Currency**.
1. Enter the following information:

     | Field names           | Description |
     | :-------------------- | :------------- |
     | **Code** | A three-letter currency code. For example: `JPY` for the Japanese Yen. It is recommended that you use the ISO 4217 currency code standard. See [https://www.iso.org/iso-4217-currency-codes.html](https://www.iso.org/iso-4217-currency-codes.html) or [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217). |
     | **Exchange Rate** | The exchange rate from the default currency. |
     | **Format** |  Specify how the price currency is displayed. For example, `¥{price}` is the format of the Japanese Yen when displayed in text. Depending on localization, a common value for this field might be something like `${price}`, if the currency is to be USD. Canadian French however, uses the symbol as a suffix, so in that case it would be `{price}$`. |
     | **Decimal point** | The decimal point character. For example, `.`. |
     | **Thousands separator** | The thousand separator character. For example, `,`. |
     | **Decimal places** | How many decimal places the currency is formatted to? For example, the US dollar is formatted to two decimal places. |

1. (Optional) Select the **Default** checkbox if you want to set this as the default currency for your organization.

    :::caution
    - The **Default** checkbox is enabled only if you select the **Enabled** checkbox.
    - You cannot delete the organization's default currency.
    :::
1. Select the **Enabled** checkbox if you want to enable this currency in your organization.
1. Click **Save**. Once the **Default** checkbox is selected and the currency is saved, you cannot deselect the **Default** checkbox.

## Edit a Currency

1. In Commerce Manager, go to **SETTINGS > Currencies**.
1. Under the **Actions** column, click the ellipsis associated with the currency **Code**.
1. Select **Edit** and modify your changes.
1. Click **Save**.

    :::caution
    You cannot deselect the **Default** checkbox. If you want to change the default currency, you must edit another currency to be the default currency.
    :::

## Delete a Currency

1. In Commerce Manager, go to **SETTINGS > Currencies**.
1. Under the **Actions** column, click the ellipsis associated with the currency **Code**.
1. Select **Delete**.

    You cannot delete the default currency. If you want to delete the default currency, you must first make another currency as the default currency. See [Edit a Currency](#edit-a-currency).

## Related Resources

- [Managing Store Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies)
- [Organization and Store Entities](/guides/key-concepts/organizations/org-level-entities)

---

## Organization Catalogs

Organizations and stores can create their own catalogs. A catalog contains the products available for sale in your organization and/or stores.

When creating a catalog, you must choose the:

- Hierarchies and nodes to include in the catalog. The hierarchies you choose determine the products that are included. You can also specify the order you want your hierarchies to display in a published catalog. You can order your hierarchies on a catalog-by-catalog basis.
- Price Books: prices for the products.

In other words, a catalog contains the products, categories, and price information that is displayed in your storefront. Hence, catalogs contain the information used to organize products for navigation menus and search facets in your shopper experience.

In a multi-store management solution:

- You can create organization catalogs. Your organization catalogs are available for your stores to use.
- Your stores can create their own catalogs.
- Your stores can create catalogs that have a combination of organization products and store products.

For example, AllGoods sell their goods in 15 different countries in 25 different languages with 10 different currencies.

- AllGoods can create their products and publish them in organization catalogs that are automatically available to their stores.
- AllGoods distributors can publish store catalogs that combine AllGoods products with the other products that they sell.
- AllGoods stores in different regions can use the AllGoods catalogs, but use different product pricing to reflect their regional differences.

## Creating Organization Catalogs

Any changes to organization-level catalogs are visible in your store when an organization catalog is republished.

1. Log into Commerce Manager as an Org Admin.
1. Select **Organizations**.
1. On the **Your organizations** page, select the organization you would like to manage from the list.
1. Go to **Merchandise > Catalogs**.
1. Click **Add Catalog**.
1. Enter the catalog's details.
2. Click **Hierarchy** to display a list of available hierarchies. You can select both organization and store level hierarchies.
1. Click **Add Price Book**. You can add up to 5 price books.
1. Click **Price Book** to display a list of available price books. You can select both organization and store level price books.
1. If you have multiple price books, you must specify a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. Enter the order of your price books in **Priority**, where the price book with the highest priority is listed first. You can specify any numbers that you want. For example, 1, 2, 3 or 100, 90, 80, and so on.
1. Select **Save**.
1. If you are publishing a catalog in a store that contains resources from an organization, you must enable the **Include Organization Resources in Catalog Publishes** checkbox.

    1. Go to **SETTINGS > General Settings**.
    1. Select the **Include Organization Resources in Catalog Publishes** checkbox.

Your organization catalogs are automatically available to all the stores within your organization.

![organization PXM catalogs](/assets/organization_catalog.png)

## Combining Organization & Store PXM Entities in Store Catalogs

In addition, your stores can create their own catalogs that contain a combination of organization and store products and price books.

If you want a combination of organization and store products, hierarchies and products, you can simply create a catalog in a store and select both organization and store hierarchies and price books.

If you want a store hierarchy to have a combination of organization and store products, then you must [duplicate the organization hierarchy](/docs/commerce-manager/product-experience-manager/hierarchies/duplicating) and assign a combination of organization and store products to the duplicated hierarchy.

If you are publishing a catalog in a store that contains resources from an organization, you must enable the **Include Organization Resources in Catalog Publishes** checkbox. See [General Settings in Commerce Manager](/docs/commerce-manager/settings/general-settings#updating-pxm-settings-to-publish-store-catalogs-containing-organizational-resources).

---

## Organization Hierarchies

Use hierarchies and nodes to group your products into categories and sub-categories.

For example, AllGoods can organize their products:

- by brand.
- create a collection for a particular distributor.
- an AllGoods distributor can create a collection that has a combination of AllGoods products and other products that they sell.

A hierarchy is a tree structure that consists of a root node with 1 or more parent nodes. Each parent node can also have one or more children nodes, and so on, creating a parent-child relationship between nodes.

A product can belong to multiple nodes in multiple hierarchies. If your store supports multiple languages, you can localize new and existing hierarchies and nodes.

When you create a catalog, you specify one or more hierarchies. Any products associated with those hierarchies are included in the catalog. When you publish a catalog, all products whose status are live appear in the catalog release. If you update a hierarchy to add, move, or delete nodes, you must republish the catalog for the changes to appear in the storefront. You can configure your hierarchies and nodes when configuring your products.

## Creating Hierarchies

A hierarchy is a tree structure that consists of a root node with one or more parent nodes. Each parent node can also have one or more children nodes, and so on, creating a parent-child relationship between nodes.

Create a hierarchy and then create the parent/child nodes.

1. Log into Commerce Manager as an Org Admin.
1. Select **Organizations**.
1. On the **Your organizations** page, select the organization you would like to manage from the list.
1. You can either:

    - Go to **Merchandise > Products** and click **All Products**, edit a product or create a new product.
    - Go to **Merchandise > Hierarchies**.

1. Click **Add Hierarchy** or **Create new hierarchy**, depending on where you are.
1. Enter the following information for a hierarchy:

    | Name | Required | Description |
    |------| --- | --- |
    | Name | Required | The name of the hierarchy. |
    | Description | Optional | A description of the hierarchy. |
    | Slug | Optional | A slug for the hierarchy. |

1. Click **Save**.

## Creating Parent/Child Nodes

A hierarchy is a tree structure that consists of a root node with one or more parent nodes. Each parent node can also have one or more children nodes, and so on, creating a parent-child relationship between nodes.

You must create a parent node first, then create your child nodes.

1. You can either:

    - Go to **Merchandise > Hierarchies**.
    - Go to **Merchandise > Products** and click **All Products**.

1. To create:

    - parent nodes in a hierarchy, click the hierarchy.
    - child nodes in a parent node, click the parent node.

1. Click **Create new node** or **Create Child Node**, depending on where you are in **Product Experience Manager**.
1. Enter the following details for a node:

    | Name        | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
    |-------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | Name        | Required | The name of the node. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.                                                                                                                                                                                                                                                                                                                                                                                                                         |
    | Description | Optional | A description of the node.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
    | Slug        | Optional | A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.                                                                                                                                                                                                                                                                                                                                                                                                                          |
    | Weight      | Optional | Enter a value to determine the order that nodes are displayed in your storefront. The node with the highest value is displayed first. The weight value must be greater than or equal to one. For example, 1, 2, 3, or 100, 90, 80, and so on. If you don’t provide a weight, child nodes are displayed in the order they were last updated, with the most recently updated child node displayed first.If you set a weight for only a few child nodes, the child nodes with a weight appear first and then other child nodes appear in the order they were last updated. |
    | Locales     | Optional | If you have activated any languages for your store: From the **Locale** list, select the language you want to use to localize your node details. You can activate and deactivate languages in Commerce Manager. You can activate a maximum of five languages. See [Using Locales in Commerce Manager]( /docs/commerce-manager/product-experience-manager/locales/).Add a localized node name and description.                                                                                                                                                           |
1. Click **Create**.
1. Click and drag your nodes to a different hierarchy at any time to reorder your nodes, depending on your requirements.

The hierarchies and nodes that you create are automatically available to all the stores within your organization.

![organization PXM entity](/assets/org_label.png)

## Duplicating Organization Hierarchies in Stores

You can duplicate an existing hierarchy. This is useful because it enables you to quickly and easily create multiple hierarchies with the same node structure. Any nodes in the existing hierarchy are also created in the duplicated hierarchy. You can optionally specify whether you want products associated with the nodes in an existing hierarchy to be associated with the nodes in the duplicated hierarchy. In addition, you can duplicate an organization hierarchy at the store level. This is useful if you want a hierarchy to contain a mixture of organization products and store products.

During the duplication process, the product associations are maintained in the duplicated hierarchy. Once an organization hierarchy is duplicated, it belongs to the given store. A store Admin can then make changes to the duplicated hierarchy, as required.

1. Log into Commerce Manager as an Org Admin.
1. Select **Stores**.
1. On the **Stores** page, select the pencil icon beside the store you would like to manage from the list.
1. Once your store details are displayed, click **Save and go to store**.
1. You can either:

    - Go to **Product Experience Manager** > **Products** and click **All Products**.
    - Go to **Product Experience Manager** > **Configurations** and, click the **Hierarchy** tab.

1. Click **...** beside the hierarchy you want to duplicate.
1. Click **Duplicate** or **Duplicate Hierarchy**, depending on where you are in **Product Experience Manager**.
1. (Required) In **Name**, enter a new name for the duplicated hierarchy.
1. (Optional) In **Description**, you can keep the existing description or enter a new description.
1. (Optional) Turn on the **Retain a products relationship** toggle to keep the products associated with the nodes in the existing hierarchy associated with the nodes in the duplicated hierarchy.
1. Click **Confirm** to save your changes.

    :::caution

    You must ensure that hierarchies in organizations and stores have unique SKUs. If a store product is created with a SKU that is already in use by an organization product, an error message is displayed. This helps maintain accurate inventory management and avoid potential conflicts between organization and store products.

    :::

3. Organize your store products in the duplicated [hierarchy](/docs/commerce-manager/product-experience-manager/hierarchies/assigning-products).
4. Your duplicated hierarchy now belongs to the store.

---

## Organization Price Books

An organization can create its own price books. You can:

- create your price books directly in your organization.
- import your price books from other company systems.

A price book contains the prices for the products. Price books can be associated with different catalogs.

- You can create organization price books. Your organization price books are available for your stores to use.
- Your stores can create their own price books.
- Your stores can create catalogs that have a combination of organization price books and store price books.

For example, AllGoods sell their goods in 15 different countries in 25 different languages with 10 different currencies.

- AllGoods can create price books for each country. All the stores in each country would use the price book created for their country.
- AllGoods can create one price book for their top-selling distributors and another one for those distributors who achieve less sales.
- For all the stores in North America, AllGoods have one price book. Using the same price book, AllGoods can create prices for specific promotions that are scheduled for use at a specific time.

In Commerce Manager, an Org Admin can manage price books in both organization and stores.

## Importing Price Books and Prices

You can create and update product price books and prices in bulk, at both organization and store level, using the Price Book Import API. This is useful, for example, if you have a promotion and want to update 50,000 product prices. Rather than having to go to each price book and manually edit 50,000 prices, you can use the Price Book Import API to bulk update all your product prices at the same time, including setting different prices for different currencies.

You can create/update:

- price books.
- prices.
    - sales pricing for products and product bundles with SKUs.
    - volume (tiers) pricing.

The following are not supported by the Price Book Import API:

- price modifiers
- SKUless bundles
- Bundle sale prices

Commerce Manager uses a [JSONL](https://jsonlines.org/) file. The JSONL file can be compressed to a GZIP file. Here is an [example of a JSONL file](/assets/example_file_all.jsonl).

A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time.

1. Log into Commerce Manager as an Org Admin.
2. Select **Organizations**.
3. On the **Your organizations** page, select the organization you would like to manage from the list.
4. Go to **Merchandise** > **Price Books**.
5. Select **Import**. Price book imports a processed sequentially in the order that you select **Import**.
6. Browse to the location of your JSONL file.
7. Select your file and click **Open**. A notification indicating whether the operation is successful is displayed. The imported price books and prices are displayed in the **All Price Books** tab.
8. Select a price book to display the imported/updated prices.
9. The import works on a "best endeavours" approach. In other words, Commerce Manager does its best to create/update the price book objects based on the file that you provide. If there are any errors, then the import is aborted and the job fails with an error. You can then use the results of the job to understand what objects were created/updated up to the point the import failed and to troubleshoot any errors. See [Import Results](/docs/api/pxm/pricebooks/import-a-price-book-and-prices#price-book-import-api-results).

## Creating Organization Price Books

Create a price book. Add a product by SKU and then add prices in each currency supported in the store. You can add new currencies under **SYSTEM** in [Organization Settings > Currencies](/docs/commerce-manager/organizations/manage-org-currencies).

1. Log into Commerce Manager as an Org Admin.
1. Select **Organizations**.
1. On the **Your organizations** page, select the organization you would like to manage from the list.
1. Go to **Merchandise > Price Books**.
1. Click **Add Price Book**.
1. Click **Save**.
1. Click the price book you just created to edit it.
1. Click **Add SKUs** to select the products to add to the price book. A list of available products to add is displayed.
1. Click **+** next to the products you want to add.
1. Enter the price for the product in the appropriate currency.
1. Click **Save**.

Your organization price books are automatically available to all the stores within your organization.

![organization PXM pricebook](/assets/organization_pricebook.png)

Your stores can publish catalogs with organization price books or a combination of organization and store price books.

---

## Organization Products

To create your organization entities, you can:

- create your products directly in your organization.
- import your products from your other company systems.

:::caution
You cannot migrate data between stores and organizations. In other words, you cannot export data from an Commerce store or organization and import the data into another Commerce store or organization.
:::

:::note
You must ensure that products in organizations and stores have unique SKUs. If a store product is created with a SKU that is already in use by an organization product, an error message is displayed. This helps maintain accurate inventory management and avoid potential conflicts between organization and store products.
:::

AllGoods have selected Commerce to support their multi-store needs. AllGoods decide to import products from their other company systems into their organization.

Once the products are available in Commerce, going forward, AllGoods can create all new products directly in Commerce.

In Commerce Manager, an Org Admin can manage entities in both organization and stores.

## Creating Organization Products

1. Log into Commerce Manager as an Org Admin.
1. Select **Organizations**.
1. On the **Your organizations** page, select the organization you would like to manage from the list.
1. You can select **Create Product** from **Task #1**, or go to **Merchandise > Products**.
1. Select **Create New**.
1. Add the [product Details](/docs/commerce-manager/product-experience-manager/products/add-product-details).
1. You can either select **Save & Exit** or **Next** to create your [product categories](#creating-product-categories).

## Importing Products to Your Organization

1. Log into Commerce Manager as an Org Admin.
1. Select **Organizations**.
1. On the **Your organizations** page, select the organization you would like to manage from the list.
1. Go to **Merchandise > Products**.
1. Select **Product Imports**.
1. Either drag your `.csv` file to the **Product Imports** tab or browse to the location of your `.csv` file and select **Import**. Your products are uploaded to your organization.
1. Select **All Products** to view your imported products.
1. You can either select **Save & Exit** or **Next** to create your [product categories](#creating-product-categories).

Your organization products are automatically available to all the stores within your organization.

![organization PXM product](/assets/org_products.png)

## Creating Organization Product Categories

Create product categories in Commerce using hierarchies and nodes. A hierarchy is a tree structure that consists of a root node with one or more parent nodes. Each parent node can also have one or more children nodes, and so on, creating a parent-child relationship between nodes.

You must create a parent node first, then create your child nodes. Each node can have one parent and multiple children.

1. You can either:

    - Select **Create new Hierarchy** from the **Hierarchies** tab, if you are creating a product.
    - Go to **Merchandise > Hierarchies**.

1. Create your [hierarchies](/docs/commerce-manager/product-experience-manager/hierarchies/creating_hierarchies).
1. Create your [parent/child nodes](/docs/commerce-manager/product-experience-manager/hierarchies/creating_nodes).
1. [Assign](/docs/commerce-manager/product-experience-manager/hierarchies/assigning-products) your products to your parent/child nodes.
1. You can either select **Save & Exit** or **Next** to create your [product templates](/docs/commerce-manager/organizations/org-pxm-entities-in-commerce-manager/create-org_pxm_templates/).

Your organization hierarchies are automatically available to all the stores within your organization.

![organization PXM hierarchy](/assets/org_hierarchy.png)

---

## Organization Templates

You can create templates for your products at both the organization and store level. Templates are a collection of attributes. Use attributes to define the characteristics of products in an organization or store or to provide an input for other purposes, such as Search Engine Optimization (SEO) or product specification. For example, a Book template might contain attributes, such as ISBN, Author, Number of pages, Year Published, or Condition (New/Used).

Although, you can create product templates for both organization and store, stores can use organization templates for store-level products. This is useful, if you have an attribute that applies to all products in all stores. You can define the template once at organization-level and relate the template to all products across all your stores.

In Commerce Manager, an Org Admin can manage templates in both organization and stores.

:::caution
- A Store Admin and Org Admin cannot create entries for the same product ID. In other words, a Store Admin cannot create an entry for a product if an Org Admin has already created an entry for the product.
- If a Store Admin creates or updates entries on an organization's template's attributes that have relationships with an organization's products, the entries do not appear on the organization's products.
:::

For example, AllGoods have a unique identifier for all their organization and store products. AllGoods can define a template for this attribute that can be applied to all their organization and store products.

## Creating Organization Product Templates

1. Log into Commerce Manager as an Org Admin.
1. Select **Organizations**.
1. On the **Your organizations** page, select the organization you would like to manage from the list.
1. Go to **Merchandise > Templates**.
1. Click **Add Template**.
1. Enter the template details and select **Save**.
1. Click **Attributes** tab.
1. Click **Add Attribute**.
1. Enter the attribute details and select **Save**.

Your organization templates are automatically available to all the stores within your organization.

![organization PXM templates](/assets/org_templates.png)

Your products can have attributes from organization templates or a combination of organization and store templates.

![organization PXM templates](/assets/org_attribute.png)

---

## Configure other Payment Gateways

## Enabling Stripe Payment Intents

Ensure that you create a [Stripe account](https://dashboard.stripe.com/login) and make a note of your secret key.

1. Log into Commerce Manager.
1. Go to **SETTINGS > Payments**.

    A list of available payment gateways is displayed. Initially, the **Stripe Payment Intents** status is **Disabled**.
1. Click **Stripe Payment Intents**.
1. In the **Secret Key** field, enter the secret key that you copied from the [Stripe dashboard](https://dashboard.stripe.com/login).
1. Select the **Enabled** checkbox to make **Stripe Payment Intents** available in Commerce Manager.
1. Click **Save**.

    The status of **Stripe Payment Intents** is now **Enabled**.

## Enabling Adyen

1. Log into Commerce Manager.
1. Go to **SETTINGS > Payments**.

    A list of available payment gateways is displayed. Initially, the **Adyen** status is **Disabled**.
1. Click **Adyen**.
1. Select the **Enabled** checkbox to enable the gateway in a production environment.
1. (Optional) Select the **Test Mode** checkbox to use the test payment method.

    To enable Adyen in the production environment, clear the **Test Mode** checkbox.
1. In the **Username** field, enter your Adyen web service. For example, ws@Company.MyCompany.
1. In the **Password** field, enter your Adyen password.
1. n the **Merchant account** field, enter your merchant account code.
1. Click **Save**. The status of **Adyen** is now **Enabled**.

## Enabling Braintree

1. Log into Commerce Manager.
1. Go to **SETTINGS > Payments**.

    A list of available payment gateways is displayed. Initially, the **Braintree** status is **Disabled**.
1. Click **Braintree**.
1. Select the **Enabled** checkbox to enable the gateway.
1. In the **Public key** field, enter your Braintree public key.
1. In the **Private key** field, enter your Braintree private key.
1. In the **Merchant ID** field, enter your Braintree Merchant ID.
1. In the **Environment** field, enter **production** or **sandbox**.
1. Click **Save**. The status of **Braintree** is now **Enabled**.

## Enabling CardConnect

1. Log into Commerce Manager.
1. Go to **SETTINGS > Payments**.

    A list of available payment gateways is displayed. Initially, the **CardConnect** status is **Disabled**.
1. Click **CardConnect**.
1. In the **Merchant ID** field, enter your CardConnect Merchant ID.
1. In the **Username** field, enter your CardConnect username.
1. In the **Password** field, enter your CardConnect password.
1. Select the **Enabled** checkbox to enable the gateway.
1. (Optional) Select the **Test Mode** checkbox to use the test payment method.

    To enable CardConnect in the production environment, clear the **Test Mode** checkbox.
1. Click **Save**.

    The status of **CardConnect** is now **Enabled**.

## Enabling Manual Gateway

1. Log into Commerce Manager.
1. Go to **SETTINGS > Payments**.

    A list of available payment gateways is displayed. Initially, the **Manual** status is **Disabled**.
1. Click **Manual**.
1. On the **Edit Manual** page, select the **Enabled** checkbox to enable the manual gateway.

## Enabling CyberSource

1. Log into Commerce Manager.
1. Go to **SETTINGS > Payments**.

    A list of available payment gateways is displayed. Initially, the **CyberSource** status is **Disabled**.
1. Click **CyberSource**.
1. In the **Merchant ID** field, enter your CyberSource Merchant ID.
1. In the **SOAP Toolkit Key** field, enter your live or test CyberSource SOAP key.
1. Select the **Enabled** checkbox to enable the gateway in a production environment.
1. (Optional) Select the **Test Mode** checkbox to use the test payment method.

    To enable CyberSource in the production environment, clear the **Test Mode** checkbox.
1. Click **Save**.

    The status of **CyberSource** is now **Enabled**.

## Enabling Authorize.net

1. Log into Commerce Manager.
1. Go to **SETTINGS > Payments**.

    A list of available payment gateways is displayed. Initially, the **Authorize.net** status is **Disabled**.
1. Click **Authorize.net**.
1. Select the **Enabled** checkbox to enable the gateway in a production environment.
1. (Optional) Select the **Test Mode** checkbox to use the test payment method.

    To enable Authorize.net in the production environment, clear the **Test Mode** checkbox.
1. In the **Login** field, enter your login ID.
1. In the **Password** field, enter your Authorize.net password.
1. Click **Save**.

    The status of **Authorize.net** is now **Enabled**.

---

## Configure Elastic Path Payments Powered by Stripe

import Video from "/src/components/CardDisplay/video"

## Prerequisites

- Ensure that you are [onboarded](/docs/payments/onboarding) to Elastic Path Payments Powered by Stripe.
- Log in to [Stripe Dashboard](https://dashboard.stripe.com/login) and make a note of your Stripe Account ID.

## Enabling the Gateway in Commerce Manager

1. Go to Commerce Manager.
1. Go to **SETTINGS > Payments**.

    A list of payment gateways that are available is displayed. Initially, the status of **Elastic Path Payments powered by Stripe** is **Disabled**.
1. Click **Elastic Path Payments powered by Stripe**.

    The **Edit Elastic Path Payments powered by Stripe** page is displayed.
1. Enter your Stripe **Account ID**.
1. Select the **Enabled** checkbox to make **Elastic Path Payments powered by Stripe** available in Commerce Manager.
1. (Optional) Select **Test mode** checkbox to use test payment method.

    To enable **Elastic Path Payments powered by Stripe** in the production environment, clear the **Test mode** checkbox.
1. Click **Save**.

    The status of **Elastic Path Payments powered by Stripe** is now **Enabled**.
1. (Optional) Disable **Elastic Path Payments powered by Stripe** at any time by closing your account or clearing the **Enabled** checkbox on the **Edit Elastic Path Payments powered by Stripe** page.

## Demos

 <Video
  mediaSrc="https://www.youtube.com/embed/4MjIofAjRao"
  mediaType="embed"
  title="Configuring Elastic Path Payments powered by Stripe" />

---

## Overview

You can view your store’s payment gateways on the **SYSTEM > Store Settings > Payment Gateways** tab.

For an overview of how payments work in Commerce, see [Payments](/docs/api/carts/payments).

:::caution
If the order total is zero or the payment is processed through non-supported payment providers, you can configure [Manual Gateway](/docs/api/payments/update-manual-gateway) to process your store payments.
:::

We support the following payment gateways:

- Elastic Path Payments powered by Stripe
- PayPal Express Checkout
- Stripe Payment Intents
- CyberSource
- Authorize.net
- Adyen
- Braintree
- CardConnect
- Manual
- Stripe

## Sorting and Filtering Payment Gateways

You can sort the payment gateway list by **Name** or **Status**.

You can filter the payment gateway list to show which gateways are **Enabled** or **Disabled**.

## Modifying a Payment Gateway

1. Select the payment gateway name on the **SETTINGS > Payments**.
1. Enter the details for the selected payment gateway.

:::note
- Each payment gateway can require different information, and the field names can be relevant to the specific gateway only.
- Contact your payment provider for details.
:::

---

## Configure PayPal Express Checkout

import Video from "/src/components/CardDisplay/video"

## Onboarding PayPal Express Checkout

If you have signed up to PayPal Express Checkout, you need to configure it with Composable Commerce to allow your customers to use PayPal Express Checkout to check out their purchases. In Commerce Manager, you can:

1. Test a sandbox account in [developer.paypal.com](https://developer.paypal.com/).
1. Enable PayPal Express Checkout in your production environment.

Follow the instructions below or, alternatively, watch a video:

<Video
  mediaSrc="https://www.youtube.com/embed/07pKiaKc1ds"
  mediaType="embed"
  title="Configuring Paypal Express Checkout" />

## Testing PayPal Express Checkout in Commerce Manager

1. Go to **SETTINGS > Payments**. A list of payment gateways that you have available is displayed. Initially, the status of PayPal Express Checkout is **Disable**.
1. Click **PayPal Express Checkout**. The **Edit PayPal Express Checkout** page is displayed. Initially, the **Onboarding Status** is **Incomplete**.
1. Select the **Enabled** checkbox to make PayPal Express Checkout available in Commerce Manager.
1. Select the **Test Mode** checkbox.
1. Click **PayPal Onboarding**.
1. Type the email address for the sandbox account that you want to use. You can go to [developer.paypal.com](https://developer.paypal.com/) to find or create a sandbox account.
1. From **Country or region** drop-down list, select the region where your sandbox account is configured.
1. Click **Next**.
1. Type your password and click **Log In**.
1. Confirm your email address to activate your account by clicking **Go back to Test Store**.
1. In **Edit PayPal Express Checkout**:

    - **Onboarding Status** changes to **Connected successfully** and,
    - **Account ID** is automatically filled with your PayPal Account ID. This means this store is ready to take transactions with PayPal Express Checkout.

    :::note
    When you manually enter the PayPal Account ID in the **Account ID** field in Commerce Manager, make sure that there is no space before and after the **Account ID** to avoid `400` error while using a `purchase` or `authorize` method to make a payment in postman.
    :::

    If you receive any onboarding errors, fix the errors and run onboarding again or contact PayPal Support.

1. Click **Save**.
1. You can test this with a different sandbox account at any time by clicking **PayPal Onboarding** and re-running PayPal onboarding. Re-running PayPal onboarding overwrites the existing Account ID.
1. You can disable PayPal Express Checkout at any time by deleting your PayPal Account ID from **Account ID** or by by clearing the **Enabled** checkbox on the **Edit PayPal Express Checkout** page.

## Enabling PayPal Express Checkout in Live Mode in Commerce Manager

1. Go to **SETTINGS > Payments**. A list of payment gateways that you have available is displayed. Initially, the status of PayPal Express Checkout is **Disable**.
1. Click **PayPal Express Checkout**. The **Edit PayPal Express Checkout** page is displayed. Initially, the **Onboarding Status** is **Incomplete**.
1. Select the **Enabled** checkbox to make PayPal Express Checkout available in Commerce Manager.
1. If selected, clear the **Test Mode** checkbox. **Test Mode** checkbox must be cleared to enable PayPal Express Checkout in a production environment.
1. Click **PayPal Onboarding**.
1. Type the email address of the live account you want to use. You can use an existing account or create a new one, depending on your requirements.

    - If this is a new email address, complete the registration form, setup your profile, and agree to the conditions to create a new account.
    - If this is an existing email address, follow the instructions to login.

1. Confirm your email address to activate your account by clicking **Go back to Elastic Path Software Inc.**.
1. In **Edit PayPal Express Checkout**:

    - **Onboarding Status** changes to **Connected successfully** and,
    - **Account ID** is automatically filled with your PayPal Account ID. This means this store is ready to take transactions with PayPal Express Checkout.

    :::note
    When you manually enter the PayPal Account ID in the **Account ID** field in Commerce Manager, make sure that there is no space before and after the **Account ID** to avoid `400` error while using a `purchase` or `authorize` method to make a payment in postman.
    :::

    If you receive any onboarding errors, fix the errors and run onboarding again or contact PayPal Support.

1. Click **Save**. From PayPal Express platform, you can verify that Elastic Path is onboarded to PayPal Express. Watch the following video:

  <Video
  mediaSrc="https://www.youtube.com/embed/M-ILzcZreM4"
  mediaType="embed"
  title="Verifying Elastic Path to Paypal Express Checkout" />

1. You can change your PayPal Account ID at any time by clicking **PayPal Onboarding** and re-running PayPal onboarding. Re-running PayPal onboarding overwrites the existing Account ID.
1. You can disable PayPal Express Checkout at any time by deleting your PayPal Account ID from **Account ID** or by clearing the **Enabled** checkbox on the **Edit PayPal Express Checkout** page.

---

## Personal Data

In Commerce, sellers have the ability to view and manage user's personal data. To update TTL setting, see [Viewing and Changing Time to Live Settings](/docs/commerce-manager/settings/general-settings#viewing-and-changing-time-to-live-settings).

## Viewing Personal Data Sets

1. In the **Commerce Manager Home** page, go to **Orders > Personal Data**.
1. The **Personal Data Sets** should be active by default.
1. In the **Type** field, select the data type you want.
1. In the **ID** field, type the ID of the data item of interest.
1. Click **Search**.
1. Use pagination links in the bottom of the page to navigate through the list.
1. You can view the Personal Data Logs by clicking on an item in the list.

## Viewing Personal Data Logs

1. In the **Commerce Manager Home** page, go to **Orders > Personal Data**.
1. Activate the **Personal Data Logs** tab by clicking it.
1. In the **Type** field, select the data type you want.
1. In the **ID** field, type the ID of the data item of interest.
1. Click **Search**.
1. Use pagination links in the bottom of the page to navigate through the list.

## Creating and viewing Erasure Requests

1. In the **Commerce Manager Home** page, go to **Orders > Personal Data**.
1. Click the **Personal Data Logs** tab.
1. In the **Type** field, select the data type you want.
1. In the **ID** field, type the ID of the data item of interest.
1. Click **Search**.
1. Find the item and in **Actions**, click **...** next to the item you want.
1. Click **Erasure Request** and in the popup window, click **Delete**.
1. Click the **Erasures Request Log** tab and make sure the Erasure Request is present and its status is **SUCCESS**.

---

## Creating Bundles

With Product Experience Manager, you can create and manage bundles. A bundle is a purchasable product comprising one or more products that you want to sell together. You can have:

- Dynamic bundles. Dynamic bundles allow your shoppers to choose their own options in a bundle.
- Bundles of bundles. Your bundle consists of child bundles.

import DynamicBundles from "/docs/partials/pxm/bundles/dynamic.mdx";

## Dynamic Bundles

<DynamicBundles></DynamicBundles>

import BundlesBundles from "/docs/partials/pxm/bundles/bundlesof.mdx";

### Creating Dynamic Bundles: An Overview

1. [Create your products](/docs/commerce-manager/product-experience-manager/products/create-products).
1. Create a bundle.
1. Specify minimum and/or maximum values for the number of product options that can be selected within the bundle. For example, if you want the shopper to select exactly 4 out of 10 options, set both the minimum and maximum values to 4 for each of the 10 product options.
1. For each product option in the bundle, specify if it is a default option by adding `"default": true` to the product options that you want to be pre-selected for the shopper.
1. [Publish the bundle to your catalog](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs) so you can display the products to your shoppers in your storefront.
1. When a shopper interacts with the bundle on your storefront, they can select the products they want from the list of options. Use the [configure a shopper bundle](/docs/api/pxm/catalog/configure-by-context-product) endpoint to capture the shoppers selections. This updates the `bundle_configuration` with the product options chosen by a shopper.
1. Once a shopper has configured their bundle, use the [add a product to a cart](/docs/api/carts/manage-carts) endpoint to add the selected bundle to the shopper’s cart.
1. When the shopper proceeds to checkout, the selected product options from the bundle are included in the order.

## Bundles of Bundles

<BundlesBundles></BundlesBundles>

### Creating bundles of bundles: an overview

To create a bundle of bundles, simply add a bundle as a component to another bundle.

1. [Create your products](/docs/commerce-manager/product-experience-manager/products/create-products).
1. Create all your child bundles.
1. Create a parent bundle and specify the product ID of your child bundle as an option of a component in your bundle. You cannot have more than 1500 options in a bundle.

## Before you Begin

- Ensure that you have created at least one price book.
- Ensure that all products that you want to add to the bundle are created with the required details.
- Ensure any child bundles that you want to add to a parent bundle are created with the required details.

:::note
 A bundle without a SKU must have a minimum quantity of components and options. Either:

 - a single option with a minimum quantity of 2.
 - 2 options, each with a minimum quantity of 1.

:::

:::caution
Commerce Manager does not sort components and component options. You must program your storefront to sort the components and component products in the order that you want.
:::

### Procedure

The steps below describe how to complete the basic information for a bundle and adding the components and product options that make up a bundle. 

1. Go to **Products** > **Bundles**. 
1. Select **Create new bundle**.
1. (Optional) Expand **Locale** drop-down list. The languages you have configured in [**Store Settings** > **Locale**]( /docs/commerce-manager/product-experience-manager/locales/) are displayed first. Custom product locales are displayed underneath. See [Configuring Locales](/docs/commerce-manager/product-experience-manager/products/configure-locales).
1. In **Basic Information**, provide the following:

    - **Name**: Name for the bundle.
    - (Optional) **SKU Number**: The SKU of the bundle.
    - **Commodity Type**: Select whether the product is physical or digital.
    - (Optional) **Description**: A description for the bundle.
    - In [**Product Tags**](/docs/commerce-manager/product-experience-manager/products/tagging-products), either:
        - enter a tag and press **Enter**. Repeat this step for each tag you want to use.
        - select **View as a comma separated list** and enter a comma separated list of tags.
    - **Slug**: A label for the bundle that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. No spaces or other characters are allowed. By default, the bundle name is used as the slug.
    - (Optional) **External Reference**: A unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.
    - (Optional) **MPN**: Manufacture Part Number (MPN).
    - (Optional) **UPC/EAN**: Universal Product Code (UPC) or European Article Number (EAN) used to scan a product in a Point of Sale (POS) system.
    - Bundle products can have rich media assets, such as product images or a file containing additional product details. Only the main image for a bundle is shown. You can only replace or delete an existing main_image. If there are other files associated with bundle, they are not shown here. You can go to [Media Management](/docs/commerce-manager/product-experience-manager/products/manage-product-media) for a product to manage these files. To add media for the bundle, do one of the following:
        - Drag and drop the file from your local directory.
        - Click **Choose File** and browse and add the file.
        - In the **add by URL** field, add the URL for the media.
    To delete media from Commerce, go to **Products** > **Media**. See **Files** in [Media](/docs/commerce-manager/product-experience-manager/product-assets/files).
1. In **Manage Bundle Components**, add the components and component products to include in your bundle. 
1. Select **Add Component**.
1. (Optional) You can specify a sort value. A sort value must be a number. You can specify any numbers that you want. For example, 1, 2, 3, or 100, 90, 80, and so on. The sort value is visible when you add the products to your catalogs. You can then use the sort value to program your storefront to display the bundle components in the order that you want.
1. In **Component Name**, enter a name for the component. The component name is the name that is displayed in your storefront.
1. In **Component Key**, enter a unique identifier to identify a component. The component key can be anything you like but it should be relatively short and must not contain any special characters.
1. (Optional) In **Minimum**, enter the minimum number of products a customer can buy. 
1. (Optional) In **Maximum**, enter the maximum number of products a customer can buy.

   :::note
   If you do not specify any minimum or maximum values for the product options in your components, your shoppers can select any combination of product options.
   :::

1. To add products to a component, select **Add Products**. The **Add products to a bundle component** pane is displayed. A list of all the available products in your store is displayed
1. You can add as many options you want. You can also filter the products by **SKU**, **Product Name**, and **Product status**, or scroll through the list.
1. Select + next to the products you want to add.
1. Close the **Add products to a bundle component** pane. The products you selected are added to the component.
1. In **Order**, you can specify a sort value for the product. A sort value must be a number. You can specify any numbers that you want. For example, 1, 2, 3, or 100, 90, 80, and so on. The sort value is visible when you add the products to your catalogs. You can then use the sort value to program your storefront to display the products in the component in the order that you want.
1. All the products are listed with the following details:

    - **Name**: The name of the product.
    - **SKU**: The SKU of the product.
    - **Status**: Whether the product is **Live** or **Draft**.

1. (Optional) By default, the quantity you configured while creating the product is displayed in **Quantity**. You can enter a new quantity, depending on your requirements. 
1. (Optional) In **Default**, select the products that you want to configure as default options. Each component can have as many defaults as the maximum number of products set for the bundle. A shopper can either select the bundle with the default products or choose products from all the components. Shoppers must either select products for all components or use the default options for all components; they cannot choose products for only one component and leave the others with default options.
1. Repeat steps 6 to 19 for each component you want to add to the bundle.
1. Select **Save Bundle**.

---

## Bundle Inventory

import BundleInventory from "/docs/partials/pxm/bundles/bundleinventory.mdx";

<BundleInventory></BundleInventory>

1. Go to **Merchandise > Products**.
1. In **All Products**, select the bundle for which you want to configure inventory.
1. Select **Actions** > **Edit** next to the bundle.
1. In the **Inventory** tab, click **Manage inventory**. The following details are displayed:

    - **Product Name**
    - **SKU**
    - **In stock**
    - **Allocated**: The amount of reserved product in stock.
    - **Available**: The amount of product available in the stock minus allocated product, where **Available** = **Total** - **Allocated**.
1. In the **Manage inventory > Actions** field, select one of the following options, and in the **Qty** field, enter the appropriate quantity:

    - **Allocate**: Reserves a number of inventory items so that you cannot sell the allocated items.
    - **Deallocate**: Reduces the number of allocated items so that you can sell the items again.
    - **Increment**: Adds stock to the total inventory.
    - **Decrement**: Reduces the specified quantity from the total inventory.

    After you update the stock, the activity is added to the log and the **Inventory log** tab displays the details of each activity.
1. Click **Next**.

---

## Bundle Pricing

import BundlePricing from "/docs/partials/pxm/bundles/bundlepricing.mdx";

<BundlePricing></BundlePricing>

## Prerequisites

Depending on the type of pricing you want to implement for your bundles, you must already have configured the following.

- If you want to assign a fixed price for all the products in a bundle, you must have already configured a price book that you want to use with your bundle. Your bundle must have a SKU.
- If you want a bundle price generated dynamically based on the sum of the component products included in a bundle, ensure that each product in the bundle has a price.

## Configuring fixed bundle pricing

If you want to assign a fixed price for all the products in a bundle, you must have already configured a price book that you want to use with your bundle. Your bundle must have a SKU.

1. Go to **Merchandise > Products**.
1. In **All Products**, select the bundle to which you want to configure pricing.
1. Select **Pricing**.
1. Turn the **Price Bundle by SKU** toggle on. (Your must bundle must have a SKU).
1. In the **Pricing** tab:

    1. To associate the bundle with a price book, from **Select Price Book** list, select a price book.
    1. Turn on the toggle for the currencies you want to use.
    1. Enter a price for each of the currencies. You can add currencies to a store in [Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
    1. In **Actions**, click **Save**.

1. If you want to add volume and sale pricing for the products in your bundle, expand **Advanced Pricing**.

    :::warning Volume Pricing for Fixed-Price Bundles Only
    The volume pricing configured in these steps applies to the **entire fixed-price bundle** (the bundle as a whole), not to individual products within the bundle. Volume pricing (quantity-based tiers) is not supported for products used as bundle components. For component-level discounts, use sale pricing with the `bundle_ids` field to target specific bundles.
    :::

    1. Click **Add Volume Level**.
    1. In **Price Book**, select the price book you want from the drop-down list.
    1. In **Min Purchase Quantity**, type the minimum quantity of products a customer must select to receive the volume price.
    1. Type a price for each of the available currencies. You can add currencies to a store under **System** in [Store Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
    1. Click **Add Level**.

1. To add a sale price to an option, click **+ Add Sale Price** and do the following:

    1. To associate the option with a price book, from **Price Book** list, select a price book.
    1. In **Sale Name**, type a name for your sale. For more information, see [Price books](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks).
    1. From **Start Date / Time - End Date / Time**, click **Start date** to display the calendar.
    1. Use the calendar to select a start date and time.
    1. Click **OK**.
    1. Use the calendar to select an end date and time.
    1. Type a price for each of the available currencies. You can add currencies under **System** in [Store Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
    1. Click **Add Sale**.

   :::tip
   When displaying your product in your storefront, you can choose to display both the list price and the sale price or the sale price only, depending on your requirements.
   ![Custom](/assets/sale-price.png)
   :::

1. Click **Next** or **Save & Exit**.

## Configuring automatic/cumulative bundle pricing

If you want the price of a bundle generated dynamically based on the sum of the component products included in a bundle, ensure that each product in the bundle has a price.

You can configure sale pricing for a bundle that uses automatic/cumulative pricing.

1. Go to **Merchandise > Products**.
1. In **All Products**, find the bundle to which you want to add a template.
1. Select **Actions** > **Edit** next to the bundle.
1. Select **Pricing**.
1. To add a sale price to an option, expand **Advanced Pricing**. If any of the products in a bundle already have a sale price, these details are displayed in **Sale Price of Options**.
1. To add a sale price, click **Find an option to add a sale price**. A list of available options is displayed.
1. From **Action**, next to the option you want to add a sale price for, select **+**.
1. Click **Add Sale Price**.

    1. To associate the option with a price book, from **Price Book** list, select a price book.
    1. In **Sale Name**, type a name for your sale. For more information, see [Price books](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks).
      1. From **Start Date / Time - End Date / Time**, click **Start date** to display the calendar.
    1. Use the calendar to select a start date and time.
    1. Click **OK**.
    1. Click **End date** to display the calendar.
    1. Use the calendar to select an end date and time.
    1. Type a price for each of the available currencies. You can add currencies in [Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
    1. Click **Add Sale**.
    1. Repeat these steps for each of the options you want to add a sale price for.
1. Click **Save & Exit**.

---

## Bundle Templates

You can add templates to your bundles. Templates are a collection of attributes. Attributes are grouped together to match a particular product type or to provide an input for other purposes, such as Search Engine Optimization (SEO) or product specification. For example, a _Book_ template might contain the attributes, such as _ISBN_, _Author_, _Number of pages_, _Year Published_, or _Condition (New/Used)_. See [Product Templates](/docs/commerce-manager/product-experience-manager/extending-products/templates)

Ensure that at least one template is available in the store.

1. Go to **Merchandise > Products**.
1. In **All Products**, select the bundle to which you want to add a template.
1. In the **Product Templates** tab, select **Add Templates**.

    The templates available for the bundle are listed.

1. To add a template to the bundle, click **+** in the template listing.

    All templates added to the bundle are displayed in the **Templates list** table. This page also provides details of the templates, such as the name and values of the attributes in the templates.

1. Select **Save & Exit**.

---

## Deleting Bundles

Deleting a bundle removes bundle information and the associated media files from the database. However, the product options in the bundle are not deleted from the database. You must republish the catalog to update the catalog release with the changes. If you want to keep your hierarchies and price books up to date, remove the deleted bundles from those resources.

Even after deleting a bundle, an order history that has the bundle still keeps the product information of the deleted bundle, such as, the product SKU, product ID, and price. However, clicking the product does not take a shopper to product details.

1. Go to **Merchandise > Bundles**.
1. Select **...** > **Delete** next to the bundle you want to delete.
1. Select **Delete**.

:::tip
You can remove bundle products from a catalog, but still keep them in the database for audit purposes.

1. Set the product status to **Draft**.
1. Remove the product from hierarchies and republish the affected catalog so that it does not appear in the storefront.
:::

---

## Editing Bundles

After editing a bundle, ensure that you republish all catalogs that contain the bundle to reflect the changes.

1. Go to **Merchandise > Bundles**.
1. In **All Bundles**, select the bundle that you want to edit.
1. Update the details as required.
1. For the changes to appear in the store, republish the catalogs that contain hierarchies with this product.

---

## Overview(Bundles)

import Video from "/src/components/CardDisplay/video"

import BundlesOverview from "/docs/partials/pxm/bundles/bundles.mdx";

<BundlesOverview></BundlesOverview>

import DynamicBundles from "/docs/partials/pxm/bundles/dynamic.mdx";

## Bundle Components and Options

<ComponentOptions></ComponentOptions>

## Dynamic Bundles

<DynamicBundles></DynamicBundles>

import ComponentOptions from "/docs/partials/pxm/bundles/components.mdx";

import BundlesBundles from "/docs/partials/pxm/bundles/bundlesof.mdx";

## Bundles of Bundles

<BundlesBundles></BundlesBundles>

## Demo

<Video
  mediaSrc="https://www.youtube.com/embed/Sds4sdDiECI"
  mediaType="embed"
  title="Bundles Configuration" />

---

## Indexing

You can configure which product fields are indexed for search and filtering. This includes enabling extended attributes from your product templates for search, faceting, and sorting.

To access indexing configuration, go to **Merchandise > Search > Indexing**.

## Store or Organization Scope

At the top of the Indexing screen, you can choose whether to configure indexing at the **Store** or **Organization** level. Only one scope can be selected at a time.

- **Store**: Index settings apply only to the current store.
- **Organization**: Index settings apply across all stores in your organization.

## Configuring Extended Attributes

The Indexing screen displays a table of all available extended attributes from your product templates. You can configure each attribute for search, faceting, and sorting.

The table includes the following columns:

| Column | Description |
|--------|-------------|
| **Attribute name** | The name of the extended attribute. |
| **Template name** | The product template the attribute belongs to. |
| **Search?** | Enable to include this attribute in full-text search. |
| **Facet?** | Enable to allow filtering by this attribute in search results. |
| **Sort?** | Enable to allow sorting search results by this attribute. |

### Enabling an Attribute for Search

1. Go to **Merchandise > Search > Indexing**.
1. Locate the attribute you want to configure in the table.
1. Toggle **Search?** to enable full-text search on this attribute.
1. Optionally, toggle **Facet?** to enable filtering by this attribute.
1. Optionally, toggle **Sort?** to enable sorting by this attribute.

:::note
After changing index settings, you must reindex your catalogs for the changes to take effect. See [Reindexing](#reindexing).
:::

## Monitoring Index Status

The right-hand pane displays the current status of your search indexes, indicating whether they are synced or if a reindex is required.

## Reindexing

When you make changes to your indexing configuration, a reindex is required for those changes to take effect in search results.

1. Review the index status in the right-hand pane.
1. If the status indicates a reindex is required, click **Re-index now**.
1. Wait for the reindexing process to complete.

:::caution
Reindexing may take some time depending on the size of your catalog. Search functionality remains available during reindexing, but results may be incomplete until the process finishes.
:::

## Related Resources

- [Setting Up Catalog Search (API)](/guides/How-To/Catalogs/Search/setting-up-search)
- [Indexable Fields API](/docs/api/pxm/catalog-search/indexable-fields)

---

## Overview(Catalog-search)

Catalog Search provides fast, relevant product search capabilities for your storefront. You can configure and manage catalog search settings directly in Commerce Manager.

To access Catalog Search, go to **Merchandise > Search**.

:::note
Catalog Search must be enabled for your store or organization before you can use it. Contact Customer Success to have this feature enabled.
:::

## Prerequisites

Before setting up catalog search, ensure you have:

- Catalog Search enabled for your store or organization
- A published catalog with products, hierarchies, and price books configured
- Appropriate permissions to manage catalogs

## Enabling Catalog Search for a Catalog

Search functionality must be enabled for each catalog you want to use it for.

1. Go to **Product Experience Manager > Catalogs**.
1. Select the catalog you want to enable search for.
1. Ensure that **Enable Search?** is turned on.
1. Save your changes and publish the catalog.

## Related Resources

- [Setting Up Catalog Search (API)](/guides/How-To/Catalogs/Search/setting-up-search)
- [Catalog Search API Reference](/docs/api/pxm/catalog-search/catalog-search-introduction)

---

## Profiles

Search profiles control how search queries are executed, including which fields to search, their relative importance, and rules for boosting or filtering results.

To access search profiles, go to **Merchandise > Search > Profiles**.

The Profiles screen displays a table of all configured search profiles with the following columns:

| Column | Description |
|--------|-------------|
| **Profile name** | The name/slug of the profile. |
| **Description** | A description of the profile's purpose. |
| **Fields** | The number of searchable fields configured. |
| **Menu** | Actions menu for managing the profile. |

One profile is marked as the default and is used when no specific profile is requested.

## Creating a Search Profile

1. Go to **Merchandise > Search > Profiles**.
1. Click **+New Profile** in the top right.
1. Enter a **Slug** (required) to identify the profile.
1. Enter a **Description** to explain the profile's purpose.
1. Configure the profile using the tabs described below.
1. Save your changes.

The profile configuration screen has the following tabs:

- **Overview**: General profile details (slug and description).
- **Searchable attributes**: Configure which fields are searchable and their weights.
- **Search scope**: Configure filters that apply to all searches using this profile.
- **Boosting rules**: Configure rules to promote or demote products.

## Configuring Searchable Attributes

The Searchable attributes tab controls which fields are included in searches and their relative importance.

1. From the profile, select the **Searchable attributes** tab or click **Edit** next to Searchable attributes.

There are two tables:

- **Core Attributes**: Standard product fields such as name, description, and SKU.
- **Extended Attributes**: Custom fields from your product templates.

Both tables have the same structure. Toggle **Searchable for this profile** to include or exclude each attribute from searches using this profile.

## Configuring Search Scope

The Search scope tab allows you to define filters that are automatically applied to all searches using this profile.

1. From the profile, select the **Search scope** tab.
1. In the **Filters** table, click **+ Add filter** to add a new filter.
1. Configure your filter criteria.

## Configuring Boosting Rules

The Boosting rules tab controls how products are ranked in search results.

1. From the profile, select the **Boosting rules** tab or click **Edit** next to Boosting rules.

### Text Match Type

Select how scores from multiple matching fields are combined:

| Option | Description |
|--------|-------------|
| **Best single field match** | Uses the highest score from any matching field. Best for general product search. |
| **Highest weighted field** | Uses the score from the highest-weighted matching field. Use when field importance matters more than match quality. |
| **Sum of all matches** | Sums scores from all matching fields. Rewards products that match in multiple fields. |

### Boost Factors

The Boost factors table allows you to increase or decrease the importance of specific attributes.

| Column | Description |
|--------|-------------|
| **Attribute** | The attribute to boost. |
| **Boost factor** | A multiplier for this attribute's contribution to relevance. Higher values increase importance. |

### Advanced Boosting Rules

Advanced boosting rules allow you to promote or demote products based on specific conditions such as categories, tags, or attribute values.

The Advanced boosting rules table has the following columns:

| Column | Description |
|--------|-------------|
| **Rule name** | The name identifying the rule. |
| **Boost factor** | The weight applied when the rule condition is met. |

To create a rule, click **+ New Rule** and select an option from the **Boost products in/with** menu.

#### Hierarchy & Node (Categories)

Boost products based on their category assignment.

1. Select **Hierarchy & node (categories)**.
1. A pane appears with a table showing **Name**, **Slug**, and **Last updated** columns.
1. To drill down into a node with children, click the **>** symbol to the left of its name.
1. Select the node you want to boost.
1. Click **Add Selected**.
1. Enter a **Boost Weight** (positive values promote, negative values demote).
1. Save the rule.

#### Product Tags

Boost products that have specific tags.

1. Select **Product tags**.
1. A list of available tags appears.
1. Select the tag you want to boost.
1. Click **Add Selected**.
1. Enter a **Boost Weight** (positive values promote, negative values demote).
1. Save the rule.

#### Product Attribute

Boost products based on attribute values.

1. Select **Product attribute**.
1. Select the attribute you want to use.
1. Click **Add Selected**.
1. In the **Configure rule** pane, set the condition:
   - Select an operator: **Equals**, **Contains**, **Not Equal**, or **Starts with**.
   - Enter a **Value** to match against.
   - Enter a **Boost Weight** (positive values promote, negative values demote).
1. Save the rule.

:::note
The available operators may vary depending on the attribute type.
:::

## Managing Profiles

Each profile in the list has a menu icon on the right with the following actions:

| Action | Description |
|--------|-------------|
| **Make default** | Set this profile as the default for all searches. |
| **Duplicate** | Create a copy of this profile. |
| **Delete** | Remove this profile. |

## Related Resources

- [Setting Up Catalog Search (API)](/guides/How-To/Catalogs/Search/setting-up-search)
- [Search Profiles API](/docs/api/pxm/catalog-search/search-profiles)

---

## Overview(Catalogs)

import Video from "/src/components/CardDisplay/video"

A catalog surfaces the product information you want to make available in a given store. It also contains information about how to organize those products for navigation and search facets in a corresponding shopper experience or storefront.

A catalog is then tied to a shopper experience/segment using catalog rules. A catalog rule defines the criteria under which to display a catalog. Catalog rules are the mechanism used to enable different shopper experience/segments to view different categorization, products and prices across multiple regions or channels. These criteria can be met by information supplied in the api request(http headers) or by attributes of a registered shopper (account and customer information). 

Catalogs do not directly define which products are included, but rather they are created using a combination of one or more hierarchies and pricebooks.

The hierarchies you assign to a catalog will determine which products appear in it, and so only the products that are associated with the selected hierarchies will be included in the catalog.

![Example Showing How Products Are Included In Catalogs](/assets/product-inclusion-in-catalogs-simplified.png)

Likewise, the price book you select will contain the prices for each of the products that appear in the catalog.

So, since your products are independently associated with hierarchies and price books, the products and corresponding prices that are available in a catalog will be determined by the hierarchies and the price books that you select for a catalog. You cannot add individual products to a catalog.

As a result, you cannot create a catalog without first setting up hierarchies and nodes for how you will categorize your products. You must also create products that include product information associated with assets and links to hierarchy nodes.

A catalog can have one or more hierarchies of products. The hierarchies contain all the products that you want to display in your organization or store. For products to be included in a catalog, the products must:
- have a `live` status.
- be associated with nodes in the selected hierarchies. You can filter your products using the **Has Node Assignment** attributes to check that the products will be included in your catalog. See [Filtering Products](/docs/commerce-manager/product-experience-manager/products/filter-products).

You can configure your catalog to have up to 5 price books. If you have multiple price books, you must specify a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. Priority is a number and the price book with the highest number has the highest priority.

A catalog was historically only able to represent a single product set/pricing model. To offer a different pricing model each audience segment would require a new catalogue. This has changed with the addition to support segmented pricing in a catalog (segmented product support coming soon).

It is now possible to configure a catalogue to support price segmentation. What this means is that a catalogue will contain all possible prices for the included products (still linked to catalogs hierarchy at the moment). To show a customer segment a specific product price, you define which pricebooks that segment should use in the catalogue rule. This allows unique pricing models to be applied at a granular level. If you specify pricebooks in the catalogue definition, those prices will be the ‘default’ price shown if no matching rule or price is found in the rules' pricebooks. This allows you the flexibility to apply ‘list prices’ to all products from a ‘list price’ pricebook and customize the actual prices on a per product/pricebook level for each customer segment.

If the catalog does not support price segmentation, a catalog must have at least one price book associated with it. If the catalog does support price segmentation, pricebooks are optional when defining the catalog. Any pricebooks supplied will be used to price products in the catalogs.

You can create multiple price books for different scenarios, such as seasonal sales, business versus retail customer pricing, and reward programs. You can use price segmentation and catalog rules to surface different prices for different scenarios/shopper segments. 

### Multiple Catalogs in a Store

Now, let's consider a scenario where you might have multiple catalogs for your store. You can add catalog rules to control  which shopper contexts can access a catalog. This allows different shoppers view different catalogs in the storefront.

![Example Showing How Multiple Shopper Segments Get Mapped To Catalogs](/assets/shopper-context-example.png)

A catalog rule defines the criteria under which to display a catalog, catalog rules are what enable you to display different catalogs across multiple regions or channels. 

They allow you to offer different products to different customer groups, such as B2B versus B2C. Catalog rules are also used to enable rewards programs with tiered pricing when a given spending level is reached, or they're used to offer a sale item for a limited time, catalog rules are defined according to criteria, including customers channel or any other user defined tags that you create. See [Configure Shopper Catalog Rules](/docs/commerce-manager/product-experience-manager/catalogs/catalog-rules).
For detailed implementation steps, see [Price Segmentation Guide](/guides/How-To/Catalogs/price_segmentation)

If a criteria rule is not met, then the default catalog and pricing are displayed to the shopper.

When you publish a catalog, the products in the hierarchies appear in a catalog release. A catalog release provides a snapshot of product information taken at the time of publication.

If you make any changes to the hierarchies, the products in a hierarchy, or price books, you must republish your catalogs. The changes do not appear in the storefront unless a catalog is re-published.

You can have many catalogs available in a store. You can use catalog rules to specify when to display your catalogs. See [Configure Shopper Catalog Rules](/docs/commerce-manager/product-experience-manager/catalogs/catalog-rules).

## Catalog Releases

When you publish a catalog, the products in the hierarchies appear in a catalog release. A catalog release provides a snapshot of product information taken at the time of publication.  Depending on how many times you have published the catalog, the latest release and the two releases prior to the latest release are available. This is useful if you want to go back to an earlier version of a catalog or see the changes that have been made between releases. You can:

- use catalog rules to specify when to display your catalog releases. See [Configure Shopper Catalog Rules](/docs/commerce-manager/product-experience-manager/catalogs/catalog-rules).
- edit catalog releases. See [Editing catalog releases](##editing-catalog-releases).
- go back to an earlier release of a catalog. See [Deleting Catalog Releases](#deleting-catalog-releases).

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/4FM4lvYtQSA"
  mediaType="embed"
  title="Configuring Catalogs & Catalog Rules in Commerce Manager" />

---

## Configure Shopper Catalog Rules

If your store has more than one catalog and you want to manage when certain catalogs are displayed, add catalog rules to control when a catalog is displayed.

:::caution
You cannot create catalog rules for an organization catalog in a store.
:::

A catalog rule contains the catalog you want to set the rule for and how you want to display it in the storefront. 

For example, you can display different catalogs based on:
* The shoppers identify. If the shopper is linked to an EPCC Account or Customer entity, the rules can be configured for specific shoppers.
* Account tags assigned to accounts. You can target groups of accounts by their tags (such as "enterprise", "premium", or "beta-testers") rather than listing individual account IDs. This is useful for B2B segmentation and managing account groups. See [Account Tags](/docs/commerce-manager/account-management/account-tags) for more information.
* How a shopper accesses your store, such as through a mobile app or a web storefront. Your shopper site would supply a HTTP header in the `EP-Channel` header - The value would be a string such as website or mobile app.
* Custom Shopper Contexts in your shopper site. You can display different catalogs to different shoppers and define custom criteria by creating tags. With tags, you can create region-specific tags so that the catalog displays only in the specified regions. Your shopper site would supply a HTTP header in the `EP-Context-Tag` - The value would be a string such as `clearance`, `gold tier`.
* You can also specify the time schedules when you want a catalog's content to display in the storefront; for example, a winter seasonal catalog appears for a specific time period and it might have different pricing from other catalogs. A catalog customized for a sale is created and published before the scheduled date. 

Caution should be used when relying on Channels and Tags if the Shopper is calling the EPCC API directly from the shoppers browser/device. The user may be able to tamper with these headers to gain access to alternative catalogs. A Backend For Frontend would be a more secure way of implementing these options.

If you only have one catalog for all customers and channels, you need not set a catalog rule. However if you have multiple catalogs, perhaps including a preview catalog, you should explicitly create a rule specifying which is your default catalog.

If a catalog rule has no criteria defined, it is the default catalog rule and will be used if no more specific catalogs with matching criteria match the shopper context.

Example Resolution Path
```mermaid
---
config:
  layout: dagre
---
flowchart TD
    A["Shopper Accesses API"] -- Shopper Context --> B("Resolve Catalog Rules")
    B --> C{"Matching Catalog Rule?"}
    C -- Yes --> D["Use Catalog Specfified In Rule"]
    C -- No --> E["Use Default Catalog"]
    E --> H["Use Catalogs Default Pricing"]
    D --> F{"Rule Specific Pricing Model?"}
    F -- Yes --> I{"Price For Product In Pricing Model?"}
    I -- Yes --> L["Apply Price From Pricing Model"]
    I -- No --> H
    F -- No --> H
    H --> M["Display Products"]
    L --> M

```

## Creating catalog rules

1. In the **Merchandise > Catalogs**.
1. Click **Add Rule**.
1. In the **Name** field, enter a name for the rule without any spaces.
1. (Optional) In the **Description** field, enter a description for the rule.
1. In the **Catalog** field, select a catalog that you want to set the rule for.
1. (Optional) In the **Accounts** field, select the account names of accounts eligible to view the catalog. When a user has logged in with the account, they see the configured catalog. If you leave this field empty, all accounts can view the catalog.
1. (Optional) In the **Account Tags** field, enter the account tag IDs (UUIDs) to target groups of accounts by their tags. This allows you to apply catalog rules to account segments (such as "enterprise", "premium", or "beta-testers") without managing individual account lists. If both account IDs and account tag IDs match with equal specificity, account ID rules take precedence. If you leave this field empty, all account tags can view the catalog.
1. (Optional) In the **Customer** field, select the email address of the customers eligible to view the catalog. If you leave this field empty, all customers can view the catalog.
1. (Optional) In the **Channels** field, enter the channels in which this catalog can be displayed.

    The channel that matches the channel specified in a catalog displays that catalog in the storefront. If you leave this field empty, all channels display the catalog. Ensure that you press enter after typing each channel name.

1. (Optional) To further restrict the eligibility criteria for this rule, in the **Tags** field, enter user-defined tag.
1. (Optional) To add a time schedule when you want the catalog to display, click [Add schedule to catalog rules](#add-schedule-to-catalog-rules).
1. Click **Save**.

### Add schedule to catalog rules

1. Click the plus icon next to **Add Schedule**.
2. Enter the start and the end date and time.
3. Click **OK**.
4. Click **Add Schedule**.

![Add Schedule to Catalog Rules](/assets/catalogrulesschedule.gif)

:::note
Commerce runs on Coordinated Universal Time (UTC) time and conforms to RFC 3339.
:::

For detailed implementation steps, see [Price Segmentation Guide](/guides/How-To/Catalogs/price_segmentation)

### Next step

Publish the catalog to apply the rule to the store. For more information, see [Publishing Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs).

## Editing catalog rules

1. In the **Merchandise > Catalogs** page, click the **Rules** tab.
1. To edit a rule, do one of the following and update the rule as required:

    - Double-click a rule.
    - Click the **...** icon in the catalog listing and click **Edit**.

1. Click **Save**.

### Next step

Publish the catalog to apply the changes to the store. For more information, see [Publishing Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs).

## Deleting catalog rules

1. To delete a catalog rule, in the **Rules** page, do one of the following:

    - Click the **...** icon in the rule listing and click **Delete**.
    - Select the checkbox in the rule listing and click **Actions > Delete**.

1. To delete more than one catalogs, select the checkbox in the rule listing of the rules that you want to delete and click **Actions > Delete**.

### Next step

Publish the catalog to apply the changes to the store. For more information, see [Publishing Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs).

## Related Resources

- [Understanding Catalogs in Product Experience Manager](https://share.vidyard.com/watch/zNEtZLHpRpBYuLZGzPwteW?)
- [Configuring Catalogs & Catalog Rules in Commerce Manager](https://share.vidyard.com/watch/3brjUM114B52gDERkFwwQt?)
- [Account Tags](/docs/commerce-manager/account-management/account-tags)
- [Account Tags API](/docs/api/accounts/account-tags)

---

## Creating Shopper Catalogs

### Before you begin

Create the products, hierarchies and price books you want to use in the catalog.

1. Go to **Merchandise > Catalogs**.
1. Click **Add Catalog**.
1. In **Name**, enter a name for the catalog.
1. (Optional) In **Description**, enter a description for the catalog.
1. In **Hierarchy**, select the hierarchies you want to add to the catalog. You can add more than one hierarchy to a catalog.
1. In **Price Books**, select a price book.

    :::note
    You cannot create a catalog without a price book.
    :::

1. (Optional) Your catalog can have up to 5 price books. This is useful, for example, if you want price books for seasonal sales, reward programs or different pricing for business and retail customers. Click **Add another Price Book**.
1. If you have multiple price books, you must specify a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. Enter the order of your price books in **Priority**, where the price book with the highest priority is listed first. You can specify any numbers that you want. For example, 1, 2, 3 or 100, 90, 80, and so on.
1. Select the additional price book you want your catalog to use.
1. Repeat steps 6-8 for each price book you want to add.

![price book stacking](/assets/pb-stacking.png)

1. Click **Save**.

---

## Deleting Catalogs

When you delete a catalog, the catalog configuration and all its releases are deleted. The hierarchies, products, and price books remain in the database. If the catalog is associated with any catalog rules, you must first update the catalog rules to remove the catalog.

- To delete a catalog, in the **Merchandise > Catalogs** page, click **...** next to the catalog you want to delete and click **Delete**.
- To delete more than one catalog, select the checkbox beside the catalogs that you want to delete and click **Actions > Delete**.

### Deleting catalog releases

1. To delete a catalog release, select the catalog whose catalog release you want to delete.
1. Select **Releases**. The latest release and the two releases prior to the latest release are displayed.
1. Select **Delete** on the release you want to delete. If you delete the latest release of a catalog, the catalog automatically goes back to the previous release. You are prompted to confirm you want to delete the release.
1. Select **Delete** to close the dialog and delete the catalog release.

---

## Editing Catalogs

If you make changes to a catalog, you must republish the catalog for the changes to appear in the store front. You can:

- Edit your catalog details.
- Add/remove hierarchies.
- Add/remove price books.

You can edit product and hierarchy details from the **Edit Catalog** tab. If you make changes to a product or hierarchy's details, you are updating the product and hierarchy details for all subsequent catalogs. However, you can go back to a previous release of a catalog. See [Deleting Catalog Releases](#deleting-catalog-releases).

1. Go to **Merchandise > Catalogs**.
1. Select a catalog. The **Edit Catalog** tab is displayed.
1. Edit the **Basic Information**, depending on your requirements.
1. In **Hierarchy**, add or remove the hierarchies you want.
1. In **Price Books**, add or remove the price books you want.
1. Select **Products List** to see a list of products displayed in this catalog. You can [filter](/docs/commerce-manager/product-experience-manager/products/filter-products) the products. For example, if you are editing a product description, you can filter using the **Description** attribute.
1. Select the product you want to edit. If you make changes to a product's details, you are updating the product for all subsequent catalogs. However, you can go back to a previous release of a catalog. See [Deleting Catalog Releases](#deleting-catalog-releases).
1. Once you have finished editing your catalog, either click **Save** to save your changes or **Publish** to save and publish your catalog.

### Editing catalog releases

A catalog release provides a snapshot of product information taken at the time of publication. Depending on how many times you have published the catalog, the latest release and the two releases prior to the latest release are available. This is useful if you want to go back to an earlier version of a catalog or see the changes that have been made between releases. In addition, you can edit your:

- Catalog release details.
- Existing products details or add a new product if it is associated with a hierarchy displayed in the catalog.
- Existing hierarchy's details.

If you make changes to a catalog release, you must republish the catalog for the changes to appear in the store front.

You can go back to an earlier release of a catalog by [deleting](#deleting-catalog-releases) the latest release.

:::note

If you want to add/remove hierarchies and price books you must [edit a catalog](#editing-catalogs).

:::

1. Go to **Merchandise > Catalogs**.
1. Select a catalog. The **Edit Catalog** tab is displayed.
1. Select **Releases**.
1. For the catalog release you want to view, select **Release Details**. The **Release Details** tab is displayed.
1. Select **Products List** to see a list of products displayed in the catalog release. You can only edit existing products or add a new product if it is associated with the hierarchy displayed in the catalog. If you make changes to a product's details, you are updating the product for all subsequent catalogs. However, you can go back to a previous release of a catalog. See [Deleting Catalog Releases](#deleting-catalog-releases).
1. Select **Hierarchies List** to see a list of hierarchies displayed in the catalog. You can only edit the existing hierarchies, you cannot associate a new hierarchy. If you make changes to a hierarchy's details, you are updating the hierarchy for all subsequent catalogs. However, you can go back to a previous release of a catalog. See [Deleting Catalog Releases](#deleting-catalog-releases).

---

## Publishing Catalogs

When you publish a catalog, the products in the hierarchies appear in a catalog release. A catalog release provides a snapshot of product information taken at the time of publication.  Depending on how many times you have published the catalog, the latest release and the two releases prior to the latest release are available. This is useful if you want to go back to an earlier version of a catalog or see the changes that have been made between releases. You can:

- use catalog rules to specify when to display your catalog releases. See [Configure Shopper Catalog Rules](/docs/api/pxm/catalog/rules).
- edit catalog releases. See [Editing catalog releases](/docs/commerce-manager/product-experience-manager/catalogs/editing-catalogs#editing-catalog-releases).
- go back to an earlier release of a catalog. See [Deleting Catalog Releases](/docs/commerce-manager/product-experience-manager/catalogs/deleting-catalogs#deleting-catalog-releases).

## Using Catalog Delta Files

When a catalog is published, the contents of the catalog are published to a delta file. This is useful if you want to share your catalog with a third-party search engine, for example. Once a catalog release has completed publishing, a link to the delta file is available in Commerce Manager.

When a catalog is published for the first time, all the content in the catalog is published. If a catalog has already been published once, then only the changes from the previous catalog are applied to the delta file. However, you can choose to generate a delta file with all the contents of a catalog release, depending on your requirements.

:::caution
Generating a full delta is resource intensive and slows down the publishing process and so should only be performed in certain circumstances, for example, when initializing an integration with a service like Algolia.
:::

## Publishing Catalogs

To publish a catalog:

1. Go to **Merchandise > Catalogs**.
1. You can either:

    - From **All Catalogs**, select **...** beside the catalog you want to publish.

  ![publish catalogs](/assets/full_publish.png)

    - Select a catalog to open it in the **Edit Catalog** tab.

1. Select **Publish**. The **Publish Confirmation** pane displays.
1. (Optional) If you want to generate a delta file with all the catalog release content, select **Generate full delta file for this publication (may extend publishing time)**.

   ![publish confirmation](/assets/publish-confirmation.png)

   :::caution
   Generating a full delta is resource intensive and slows down the publishing process and so should only be performed in certain circumstances, for example, when initializing an integration with a service like Algolia.
   :::

1. Select **Publish**.

## Viewing Catalog Publications Status

By selecting **Activity**, you can view the status of your catalog publications in Commerce Manager. This enables you to see at a glance the status of your catalog publications, and to quickly and easily detect any potential problems.

To view catalog publications in Commerce Manager:

1. Select **Activity** from anywhere in Commerce Manager.

   ![Activity button](/assets/activity_button.png)

2. From the **Activity Type** list, select **Catalog Publications**.

   When you expand an individual catalog, the following information is displayed.

   ![catalog publication activity](/assets/catalog_publication.png)

   - the number of catalog releases. Published catalogs are limited to the current release and two releases prior to the current release. This means that the **Number of releases** is three or less.
   - the date and time a catalog release was created.
   - the date and time the catalog release finished publishing.
   - the status of a catalog publish.

        - **PENDING** - Commerce has received the request but is currently busy processing other requests.
        - **IN_PROGRESS** - Commerce has started creating the catalog release.
        - **PUBLISHED** - The catalog release is published.
        - **FAILED** - The catalog publish has failed.

  - A link to the delta file. See [Using Catalog Delta Files](#using-catalog-deltas).

---

## Manage Currencies in Stores

In your store, you can display prices to customers in their local currency. You can configure up to ten currencies per store.

You can do this using:

- [Commerce Manager](#managing-currencies)
- [Currencies API](/docs/api/pxm/currencies/currencies-introduction)

After a customer selects a locale, the product prices in the catalog, carts, and orders are displayed in the currency for that locale. Order totals and taxes are calculated in the same currency. See [Using Currencies in Catalogs, Carts and Orders](#using-currencies-in-ep-pxm-products-and-catalogs-carts-and-orders).

In Commerce Manager, under **SYSTEM > Store Settings > Currencies** tab, an **ORG** tag is displayed to indicate that the currency belongs to your organization. For more information about organization-level currencies, see [Managing Currencies in Organizations](/docs/commerce-manager/organizations/manage-org-currencies).

## Currency Use Cases

You can use [Currencies API](/docs/api/pxm/currencies/currencies-introduction) or Commerce Manager to achieve the following goals:

- [Set-up default currency](#set-a-default-currency)
- [Set-up multiple currencies](#create-a-currency)
- [Delete or disable existing currencies](#delete-or-disable-currency)
- [Edit existing currencies](#edit-currency)

:::note
In Commerce Manager, when you create a new currency in your organization, a store belonging to that organization may not immediately inherit that currency. You might have to click the three dots associated with the currency **Code**, select **Edit**, and then click **Save** to see the new organization-level currency. See [Edit a Currency](#edit-a-currency).
:::

## Managing Currencies

Configure currencies only for the locales in which you do business, and select one of the currencies to be the default currency. If a default currency is not selected, the store uses the United States Dollar (USD).

### Create a Currency

You can create a currency using [Create a Currency](/docs/api/pxm/currencies/create-a-currency) endpoint or Commerce Manager. You can configure several currency types for your project.

1. In Commerce Manager, go to **SETTINGS > Currencies** tab.
1. Click **New Currency**.
1. Enter the following information:

     | Field names   | Description |
     | :------------- | :------------- |
     | **Code** | A three-letter currency code. For example: `JPY` for the Japanese Yen. It is recommended that you use the ISO 4217 currency code standard. See [https://www.iso.org/iso-4217-currency-codes.html](https://www.iso.org/iso-4217-currency-codes.html) or [https://en.wikipedia.org/wiki/ISO_4217](https://en.wikipedia.org/wiki/ISO_4217). |
     | **Exchange Rate** | The exchange rate from the default currency. |
     | **Format** |  Specify how the price currency is displayed. For example, `¥{price}` is the format of the Japanese Yen when displayed in text. Depending on localization, a common value for this field might be something like `${price}`, if the currency is to be USD. Canadian French however, uses the symbol as a suffix, so in that case it would be `{price}$`. |
     | **Decimal point** | The decimal point character. For example, `.`. |
     | **Thousands separator** | The thousand separator character. For example, `,`. |
     | **Decimal places** | How many decimal places the currency is formatted to? For example, the US dollar is formatted to two decimal places.

1. (Optional) Select the **Default** checkbox if you want to set this as the default currency for your store.
1. Select the **Enabled** checkbox to enable this currency in your store.
1. Click **Save**.

### Delete or Disable a Currency

If a currency is no longer needed, you can delete it. Deleting destroys that currency object. The currency is automatically deleted from all products that have used it. If this was the only currency set up for the product, the product has no currency, and if used in a request, the default currency is used instead.

You cannot delete the default currency. If you want to delete the default currency, you must make another currency the default. See [Set a default currency](#set-a-default-currency).

You can do this using the [Delete a Currency](/docs/api/pxm/currencies/delete-a-currency) endpoint or Commerce Manager.

If a currency is no longer needed but you still want to retain it for archiving purposes, disable it. Disabled currencies still show in the currency header, but they can’t be actively used. You can do this using the [Update a Currency](/docs/api/pxm/currencies/update-a-currency) endpoint or Commerce Manager.

#### Disable a currency in Commerce Manager

1. In Commerce Manager, go to **SETTINGS > Currencies**.
1. On the currency you want to disable, from **Actions**, select the ellipsis.
1. Select **Edit**. The **Edit *currency name* currency** dialog is displayed.
1. Clear the **Enabled** checkbox.
1. Click **Save**.

#### Delete a currency in Commerce Manager

1. In Commerce Manager, go to **SETTINGS > Currencies**.
1. On the currency you want to delete, from **Actions**, select the ellipsis.
1. Select **Delete**.

### Edit a Currency

Editing the existing currency updates all products that have that currency set-up. You can edit the currency using the [Update a Currency](/docs/api/pxm/currencies/update-a-currency) endpoint or Commerce Manager.

1. In Commerce Manager, go to **SETTINGS > Currencies**.
1. On the currency you want to edit, from **Actions**, select the ellipsis.
1. Select **Edit**.

    The **Edit *currency name* currency** dialog is displayed.
1. Make your changes and click **Save**.

### Sort and filter currencies in Commerce Manager

You can sort the currencies list by **Code** or **Status**.

You can filter the currencies list to show which currencies are **Enabled** or **Disabled**.

### Set a Default Currency

The default currency is USD and it’s also enabled by default. You can set up any currency as default, as long as the currency is enabled.

In the API, the default currency is used as a fallback currency in a request, if no currency header is provided.

You can configure a default currency using either the [Update a Currency](/docs/api/pxm/currencies/update-a-currency) endpoint or Commerce Manager.

1. In Commerce Manager, go to **SETTINGS > Currencies**.
1. On the currency you want to set as default, from **Actions**, select the ellipsis.
1. Select **Edit**. The **Edit *currency name* currency** dialog is displayed.
1. Select the **Default** checkbox.
1. Click **Save**.

## Using Currencies in Catalogs, Carts and Orders

After a customer selects a locale, the product prices in the catalog, carts, and orders are displayed in the currency for that locale. Order totals and taxes are calculated in the same currency. You cannot have a cart or order where product prices are in mixed currencies.

## Catalogs

When a request comes into a gateway, the currency settings are attached to the request based on the `x-moltin-currency` header the user passes in. If the currency is not specified, the project’s default currency is used. The currency settings are responsible for adapting the price format to the currency in use.

For projects that support multiple currency, use the `x-moltin-currencies` header that contains the formatting detail for all currencies available to the project.

```json
[
    {
        "code": "GBP",
        "exchange_rate": 1,
        "format": "\u00A3{price}",
        "decimal_point": ".",
        "thousand_separator": ",",
        "decimal_places": 2
    },
    {
        "code": "USD",
        "exchange_rate": 0,
        "format": "${price}",
        "decimal_point": ".",
        "thousand_separator": ",",
        "decimal_places": 2
    }
]
```

This allows you to have a collection of all currencies, including ones that are disabled.

### Carts and Orders

Carts don’t support multiple currencies. If you add products with mixed currencies, the products automatically fall back and use the default currency. Otherwise, `display_price` is `0`.

Price formatting is handled by Composable Commerce. After a cart converts into an order, the header provides all formatting details available for the currency specified in the order. If the currency doesn’t exist in the project, then currencies `GET` returns sensible defaults, so the `display_price` values won’t be formatted, but the correct order currency is displayed.

When the request gets to orders, the `currency-related` information from the header is put into the meta object of the response.

The formatted price can be found outside the regular price object for a product, in the meta object, which also includes timestamps, stock detail, etc. When getting a list of orders, every order is displayed in the currency the order was taken in.

## Related Resources

- [Currencies](/docs/api/pxm/currencies/currencies-introduction)
- [Managing Currencies in Organizations](/docs/commerce-manager/organizations/manage-org-currencies)

---

## Product Templates Attributes

## Templates

Templates are a collection of attributes. Attributes are grouped together to match a particular product type or to provide an input for other purposes, such as Search Engine Optimization (SEO) or product specification. For example, a *Book* template might contain the attributes, such as *ISBN*, *Author*, *Number of pages*, *Year Published*, or *Condition (New/Used)*.

:::caution
Custom names and values prefixed with `$` are not supported.
:::

You must create a template before creating attributes.

You can only assign an attribute to one template. If you want to assign an attribute to more than one template, you must create an attribute for each template.

If you want to delete a template, we recommend deleting all attributes assigned to a template before deleting the template.

Once a template is deleted, you cannot reassign a new template to the attributes or use the attributes again.

### Creating templates

1. In the **Merchandise > Products > Templates** page, click **Templates** tab.
1. Click **Add Template**.
1. Enter the following details:

    - **Name**
    - **Slug**
    - **Description**

1. To change the status, click the **Status** toggle. You can set either **Live** or **Draft** status for the template.
1. Click **Save**

### Viewing and editing templates

1. In the **Merchandise > Products > Templates** page, click **Templates** tab.
1. Click a template.
1. View or update the following details as required:

    - **Name**
    - **Slug**
    - **Description**
    - **Status**

1. All attributes assigned to the template are displayed in a table. However, you can only view the attributes, you cannot edit or delete the attributes. If you want to remove an attribute from the template, see [Deleting Attributes](/docs/api/flows/delete-a-field).
1. Click **Save** to save your template.

### Deleting templates

We recommend [deleting Attributes](#deleting-attributes) assigned to a template before deleting the template. You cannot assign a new template to the attributes or use the attributes again after deleting the template.

1. Go to **Merchandise > Products > Templates**.
1. Select **Templates**.
    - If you want to delete more than one template, select the checkboxes of the templates that you want to delete. In **Actions**, select **...** and select **Delete**.
    - If you only want to delete one template, in **Actions**, select **...** next to the template you want to delete and select **Delete**.
1. A dialog is displayed that warns you that the template will no longer be available to use or to associate attributes to.
1. Click **Delete** to close the dialog box and delete the template.

## Attributes

Use attributes to define the characteristics of products in a store. For example, you can assign attributes such as, color and size, to a shirt. When a shopper searches for a specific item, attributes help stores to return the products that match the search criteria. For example, when a shopper searches for a large blue shirt, all shirts that are large and blue are returned as the search result.

In attributes configuration, you can specify whether an attribute is required. This is useful when only a subset of attributes is relevant for a specific product. For example, you can set *size* attribute as required for a T-shirt and *color* attribute as optional. This means you don't have to use all the attributes defined in a template if they aren't needed for a particular product. For a template that has 50 attributes, for a particular product, you might only need 3 of these attributes. With this feature, you can mark the remaining 47 attributes as optional. When you search for the product, only the relevant attributes (the 3 you need) are returned. This makes the search results more concise and relevant.

### Creating attributes

#### Before you begin

- Ensure that at least one template is created.

#### Procedure

1. Go to **Merchandise > Products > Attributes**.
1. Select **Add Attribute**.
1. In the **Name** field, enter a name for the attribute.
1. To mark an attribute as required, select the **Required Attribute** toggle.
1. To set the status of an attribute to *Live*, select the **Attribute Status** toggle.
1. If you want to hide this attribute in your published catalog if no data has been set, select the **Hide Empty Template Fields** toggle.
1. In the **Description** field, enter a description for the attribute.
1. In the **Slug** field, enter a unique slug for the attribute. These slugs are shown in the results when you search for a product with attributes.
1. (Optional) In the **Default Value** field, enter a default value. You can set this value to use when a user does not provide a value for the attribute and the attribute value is required.
1. In the **Field Type** field, select one of the following options:

    - **Boolean**
    - **Float**
    - **Integer**
    - **Date**
    - **String**

1. In the **Template** field, select a template. You can link an attribute to only one template.
1. In the **Order** field, specify the order in which this attribute is returned relative to the rest of the flow fields.
1. Click **Save**.

### Editing attributes

Ensure that you republish the catalog release after editing hierarchies to reflect the changes in the storefront.

:::caution
You cannot edit the **Field Type** or **Template** settings. In other words, once an attribute is created, you cannot change it's field type or assign it to another template.
:::

1. Go to **Merchandise > Products > Attributes**.
1. Double-click the attribute that you want to edit.
1. Update the details as required.
1. Click **Save**.

For the changes to appear in the storefront, you must republish the affected catalogs.

### Deleting attributes

1. Go to **Merchandise > Products > Attributes**.
1. Select **Attributes**.
    - If you want to delete more than one attribute, select the checkboxes of the attributes that you want to delete. In **Actions**, select **...** and select **Delete**.
    - If you only want to delete one attribute, in **Actions**, select **...** next to the attribute you want to delete and select **Delete**.

## Related Resources

- [Product Templates](/docs/api/flows/flows)
- [Product Attributes](/docs/api/flows/fields)
- [Price books](/docs/api/pxm/pricebooks)
- [Catalog](/docs/api/pxm/catalog)
- [Create a template](/docs/api/flows/create-a-flow)
- [Create an attribute](/docs/api/flows/create-a-field)

### Demos

<iframe class="vidyard_iframe"
  mediaType="embed"
  title="Product Templates" src="//play.vidyard.com/qjtj94hXJQMaaAHU8inLqS.html?" width="640" height="360" scrolling="no" frameborder="0" allowtransparency="true" allowfullscreen referrerpolicy="no-referrer-when-downgrade"></iframe>

---

## Assigning Products

import Video from "/src/components/CardDisplay/video"

You can assign products to hierarchies and their child nodes. This determines how the products are displayed in the shopping catalog of your storefront. For example, a Nike basketball shoe for men can be assigned to the following hierarchies and nodes:

- Brands > **Nike**
- Shoppers > **Men**
- Footwear > Sports > **Basketball**

### Assigning products to a node

To add products to a node in a hierarchy:

1. Go to **Merchandise > Hierarchies**.
1. Select the hierarchy that contains the nodes whose products you want to assign.
1. Select **Nodes**.
1. Navigate to the node to which you want to add products. If there are no nodes created for this hierarchy, you must create them before you can assign any products.
1. Select **...**  > **Edit Node**.
1. Select **+ Add Products**. The **Add products to node** pane is displayed.
1. You can search for the products you want to add. See [Filtering Products][.
1. Select **+** next to the products you want to add. You can select as many as you like.
1. Close the **Add products to node** pane.
1. Select **Save and continue**.

![assigning products to a node](/assets/assigning_products.gif)

## Dissociating Products From a Node

You can dissociate multiple products from a node.

To dissociate products from a node in a hierarchy:

1. Go to **Merchandise > Hierarchies**.
1. Select the hierarchy that contains the nodes whose products you want to assign.
1. Select **Nodes**.
1. Navigate to the node to which you want to add products.
1. Select **...**  > **Edit Node**.
1. Scroll down to Products.
1. Select **Delete** next to the products you want to unassign.
1. Select **Save and continue**.

![dissociating products from a node](/assets/dissociating_products.gif)

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/4-ccMytvaNE"
  mediaType="embed"
  title="Understanding Hierarchies in Product Experience Manager" />
<Video
  mediaSrc="https://www.youtube.com/embed/4FM4lvYtQSA"
  mediaType="embed"
  title="Configuring Hierarchies in Product Experience Manager" />

---

## Creating Hierarchies

import Video from "/src/components/CardDisplay/video"

A hierarchy is a tree structure that consists of a root node with one or more parent nodes. Each parent node can also have one or more children nodes, and so on, creating a parent-child relationship between nodes.

Create a hierarchy and then create the parent/child nodes.

1. Go to **Merchandise > Hierarchies**.
1. Select the **Hierarchies** tab.
1. Select **Add Hierarchy**.
1. Enter the following information for a hierarchy:

    | Name        | Required | Description                     |
    |-------------|----------|---------------------------------|
    | Name        | Required | The name of the hierarchy.      |
    | Description | Optional | A description of the hierarchy. |
    | Slug        | Optional | A slug for the hierarchy.       |

1. Select **Save**.
1. You can edit a hierarchy at any time by selecting **...** > **Edit** next to the hierarchy you want to edit.

### Next steps

[Create Parent/Child Nodes](/docs/commerce-manager/product-experience-manager/hierarchies/creating_nodes)

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/4-ccMytvaNE"
  mediaType="embed"
  title="Understanding Hierarchies in Product Experience Manager" />
<Video
  mediaSrc="https://www.youtube.com/embed/4FM4lvYtQSA"
  mediaType="embed"
  title="Configuring Hierarchies in Product Experience Manager" />

---

## Creating Parent/Child Nodes

import Video from "/src/components/CardDisplay/video"

A hierarchy is a tree structure that consists of a root node with one or more parent nodes. Each parent node can also have one or more children nodes, and so on, creating a parent-child relationship between nodes.

You must create a parent node first, then create your child nodes.

1. Go to **Merchandise > Hierarchies**.
1. Select the hierarchy where you want to add the parent/child nodes.
1. Select **Nodes**. Create your parent/child nodes.

    ![node view](/assets/node_view.gif)

1. Enter the following details for a node:

    | Name | Required | Description |
    | --- | --- | --- | --- |
    | Name | Required | The name of the node. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies. |
    |  Description | Optional |  A description of the node. |
    | Slug | Optional | A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies. |
    | Weight | Optional | Enter a value to determine the order that nodes are displayed in your storefront. The node with the highest value is displayed first. The weight value must be greater than or equal to one. For example, 1, 2, 3, or 100, 90, 80, and so on. If you don’t provide a weight, child nodes are displayed in the order they were last updated, with the most recently updated child node displayed first.If you set a weight for only a few child nodes, the child nodes with a weight appear first and then other child nodes appear in the order they were last updated. |
    | Locales | Optional |  If you have activated any languages for your store: From the **Locale** list, select the language you want to use to localize your node details. You can activate and deactivate languages in Commerce Manager. You can activate a maximum of five languages. See [Using Locales](/docs/commerce-manager/product-experience-manager/locales/).Add a localized node name and description. |

1. You can edit a node at any time by selecting **...** > **Edit node**.
1. Select **Save and Continue** to save your changes.

### Next steps

[Assign products to your nodes](/docs/commerce-manager/product-experience-manager/hierarchies/assigning-products)

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/4-ccMytvaNE"
  mediaType="embed"
  title="Understanding Hierarchies in Product Experience Manager" />
<Video
  mediaSrc="https://www.youtube.com/embed/4FM4lvYtQSA"
  mediaType="embed"
  title="Configuring Hierarchies in Product Experience Manager" />

---

## Deleting Hierarchies & Nodes

import Video from "/src/components/CardDisplay/video"

When you delete a hierarchy, the hierarchy and all its descendant nodes are deleted from the database. The products that were associated with the hierarchy remain in the database and can be used with other hierarchies.

1. Go to **Merchandise > Hierarchies**.
1. Select the checkboxes of the hierarchies that you want to delete.
1. Select **...** > **Delete** next to the hierarchy you want to delete.
1. You can delete more than one hierarchy at a time by checking each of the hierarchies you want to delete and selecting **Actions** > **Delete**.

:::caution

The updates in hierarchies do not appear in the storefront until you republish the affected catalog releases.

:::

![deleting hierarchies](/assets/delete_hierarchy.gif)

## Deleting Parent/Child Nodes

When you delete a parent/child node, the parent/child node and all its descendant nodes are deleted from the database. The products that were associated with the parent/child node remain in the database and can be used with other hierarchies and parent/child nodes. If you want to keep the child nodes, change the parent for each child of the node you want to delete before deleting the node.

1. Go to **Merchandise > Hierarchies**.
1. Select the hierarchy that the parent/child nodes you want to delete belongs to.
1. Select **Nodes**.
1. Navigate to the node that you want to delete.
1. Select **...** > **Delete** next to a parent/child node to delete the parent/child node.
1. You can delete more than one node at a time by checking each of the nodes you want to delete and selecting **Actions** > **Delete**.

:::caution

The updates do not appear in the storefront until you republish the affected catalog releases.

:::

![deleting nodes](/assets/delete_node.gif)

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/4-ccMytvaNE"
  mediaType="embed"
  title="Understanding Hierarchies in Product Experience Manager" />
<Video
  mediaSrc="https://www.youtube.com/embed/4FM4lvYtQSA"
  mediaType="embed"
  title="Configuring Hierarchies in Product Experience Manager" />

---

## Duplicating Hierarchies & Nodes

import Video from "/src/components/CardDisplay/video"

You can duplicate an existing hierarchy or node. This is useful because it enables you to quickly and easily create multiple hierarchies and nodes with the same node structure.

When you duplicate a hierarchy or a node, you can specify a new name and/or a new description for the duplicated hierarchy or node. All other attributes, such as slug and locales, stay the same.

Any nodes in the existing hierarchy or node are also created in the duplicated hierarchy.

In addition, when duplicating a hierarchy, you can specify whether you want products associated with the nodes in an existing hierarchy to be associated with the nodes in a duplicated hierarchy. Duplicating a node does not retain product relationships.

### Duplicating hierarchies

The following steps describe duplicating hierarchies.

1. Go to **Merchandise > Hierarchies**.
1. Select **...** > **Duplicate** from one of hierarchies in the table.
1. (Required) In **Name**, enter a new name for the duplicated hierarchy.
1. (Optional) In **Description**, you can keep the existing description or enter a new description.
1. (Optional) Turn on the **Retain a products relationship** toggle to keep the products associated with the nodes in the existing hierarchy associated with the nodes in the duplicated hierarchy.
1. Click **Confirm** to save your changes.

![duplicating hierarchies](/assets/duplicate_hierarchy.gif)

### Duplicating nodes

When duplicating a node, the child nodes are not duplicated and the existing products in the node cannot be assigned to the duplicate node. Essentially, when you are copying a node you are copying the name, description and slug.

The following steps describe duplicating nodes.

1. Go to **Merchandise > Hierarchies**.
1. Select the hierarchy whose node you want to duplicate.
1. Select **Nodes**.
1. Navigate to the node you want to duplicate.
1. Select **...** > **Duplicate Node**.
1. (Required) In **Name**, enter a new name for the duplicated node.
1. (Optional) In **Description**, you can keep the existing description or enter a new description.
1. In **Slug**, you can keep the existing slug or enter a new one.
1. Click **Save** to save your changes.

![duplicating nodes](/assets/duplicate_node.gif)

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/4-ccMytvaNE"
  mediaType="embed"
  title="Understanding Hierarchies in Product Experience Manager" />
<Video
  mediaSrc="https://www.youtube.com/embed/4FM4lvYtQSA"
  mediaType="embed"
  title="Configuring Hierarchies in Product Experience Manager" />

---

## Overview(Hierarchies)

import Video from "/src/components/CardDisplay/video"

import HierarchyOverview from "/docs/partials/pxm/hierarchies/hierarchies.mdx";

<HierarchyOverview></HierarchyOverview>

## Hierarchies and Catalogs

import HierarchyCatalog from "/docs/partials/pxm/hierarchies/hierarchycatalogs.mdx";

<HierarchyCatalog></HierarchyCatalog>

## Sorting Node Order 

You can sort the order of your nodes, regardless of where the nodes are in the hierarchy. Enter a value to determine the order that nodes are displayed in your storefront. The node with the highest value is displayed first. The weight value must be greater than or equal to one. For example, 1, 2, 3, or 100, 90, 80, and so on.

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/4-ccMytvaNE"
  mediaType="embed"
  title="Understanding Hierarchies in Product Experience Manager" />
<Video
  mediaSrc="https://www.youtube.com/embed/4FM4lvYtQSA"
  mediaType="embed"
  title="Configuring Hierarchies in Product Experience Manager" />

---

## Jobs(Jobs)

Several tasks that you perform in Commerce Manager trigger a job.

- product [import](/docs/commerce-manager/product-experience-manager/product-import/product-importer).
- product [export](/docs/commerce-manager/product-experience-manager/product-export/export-products-cm).
- price book [import](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks#importing-price-books-and-prices).
- [duplicating hierarchies](/docs/commerce-manager/product-experience-manager/hierarchies/duplicating).
- [building child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products).

## Job Lifecycle

A job has the following lifecycle.

![job lifecycle](/assets/job-lifecycle.png)

By selecting **Activity**, you can view the status of your jobs in Commerce Manager. This enables you to see at a glance the status of your jobs, and to quickly and easily detect any potential problems.

![activity button](/assets/activity_button.png)

To view jobs in Commerce Manager:

1. Click on **Activity** (notification icon) from the left navigation menu above the profile.
2. From the **Activity Type** list, select **Jobs**.

    When you expand an individual job, the information that is displayed depends on the activity you performed.

    ![product export job](/assets/product_export_job.png)

    Each job has the following information:

    - the unique Job ID generated when a job is created.
    - the date and time the job started.
    - the status of the job:

       - **PENDING** - Commerce has received the request but is currently busy processing other requests.
       - **STARTED** - Commerce has started processing the job.
       - **SUCCESS** - The job has successfully completed.
       - **FAILED** - The job has failed. See [Get job errors](/docs/api/pxm/products/get-job).

    In addition to the above information:

    - For a **Price Book Import**, you can see the job duration.
    - For a **Product Export**, you can also download your export file.

---

## Using Locales

You can localize product names and descriptions when creating your products.

By default, there are a number of language codes available. You activate locales in Commerce Manager in **SETTINGS > Locales**.

By default, there are a number of language codes available to activate. The product names and descriptions for those language codes are editable in Commerce Manager only if they are enabled in settings. If you want to use a language code that is not available by default, then you can add a localized product name and description for this language using [create a product](/docs/api/pxm/products/create-product) API request.

You can only activate a maximum of 5 languages within Commerce Manager.

## Adding a New Locale

1. Go to the **SETTINGS > Locales**, select the language names you want to activate.
1. Click **Save**. The status of the language names you have selected changes to **Active**.
1. Once you have selected a language name, in [**Products** > **Product details**](/docs/commerce-manager/product-experience-manager/products/configure-locales), you can create product information for your products in the languages you have selected.
1. You can make an active language inactive by clearing its checkbox.

![Checkbox](/assets/locales3.png)

---

## Price Books(Pricebooks)

import Video from "/src/components/CardDisplay/video"

A price book contains the prices for the products in a catalog. Catalogs with the same hierarchies of products can be associated with different price books.

A price book contains a list of product SKUs and the prices you want to charge for those products. If your store supports multiple currencies, a price book can contain product prices in each of the supported currencies. See [Manage Currencies in Stores](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).

Each catalog must have at least one price book.  A price book can be associated with multiple catalogs.

You can configure your catalog to have up to 5 price books. Price book stacking allows you to create multiple price books for different scenarios, such as seasonal sales, business versus retail customer pricing, and reward programs. If you have multiple price books, when you create a catalog, you must configure a priority for your price books. Product prices are displayed in the catalog according to the priority of the price books. For example, you may have products that have different prices based on region. You can have a price book with the standard retail pricing and then have a second price book that has different pricing for a different region. See [Create a catalog](/docs/commerce-manager/product-experience-manager/catalogs/creating-catalogs).

With catalog rules, you can specify when to display these catalogs based on the shopper context. See [Configure Shopper Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/creating-catalogs) and [Configure Shopper Catalog Rules](/docs/commerce-manager/product-experience-manager/catalogs/catalog-rules).

You can use price modifiers to change the prices of your child products. By default, child products inherit the same price as their parent products. Using price modifiers, you can enable child products to inherit a different price. For example, this enables you to configure the price of child products to be lower than its parent product, without having to individually update the prices of your child products. There are two types of price modifier.

| Modifier    | Description |
|:------------| :--- |
| `Increment` | Increases the price of a product. |
| `Decrement` | Decreases the price of a product. |

You can create and update product price books and prices in bulk, at both organization and store level, using the Price Book Import API. This is useful, for example, if you have a promotion and want to update 50,000 product prices. Rather than having to go to each price book and manually edit 50,000 prices, you can use the Price Book Import API to bulk update all your product prices at the same time, including setting different prices for different currencies.

In your storefront, the product prices are displayed in the currencies you have configured for your store. If a product in the catalog does not have a price for a currency in the price book, the product is displayed without a price.

## Importing Price Books and Prices

You can create/update:

- price books.
- prices.
   - sales pricing for products and product bundles with SKUs.
   - volume (tiers) pricing for standalone products and fixed-price bundles.

The following are not supported by the Price Book Import API:

- price modifiers
- SKUless bundles
- Bundle sale prices
- Volume pricing for products used as bundle components

Commerce Manager uses a [JSONL](https://jsonlines.org/) file. The JSONL file can be compressed to a GZIP file. Here is an [example of a JSONL file](/assets/example_file_all.jsonl).

A file can include up to 50,000 objects. If you have more than 50,000 objects, then you must create a separate file, and import each file, one at a time.

1. Go to **Merchandise > Price Books**.
2. Select **Import**. Price book imports a processed sequentially in the order that you select **Import**.
3. Browse to the location of your JSONL file.
4. Select your file and click **Open**. A notification indicating whether the operation is successful is displayed. The imported price books and prices are displayed in the **All Price Books** tab.
5. Select a price book to display the imported/updated prices.
6. The import works on a "best endeavours" approach. In other words, Commerce Manager does its best to create/update the price book objects based on the file that you provide. If there are any errors, then the import is aborted and the job fails with an error. You can then use the results of the job to understand what objects were created/updated up to the point the import failed and to troubleshoot any errors. See [Import Results](/docs/api/pxm/pricebooks/import-pricebook#tag/Price-Book-Import).

## Creating Price Books

Create a price book. Add a product by SKU and then add prices in each currency supported in the store. You can add new currencies under **System** in [Store Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).

1. Go to **Merchandise > Price Books**.
1. Click **Add Price Book**.
1. In the **Name** field, enter a name for the price book. Price books must have a unique name.
1. (Optional) In the **Description** field, enter a description for the price book.
1. Click **Save**.

You can add products and price only after creating a price book.

## Adding Products and Prices to a Price Book

To add products and prices to a price book:

1. Go to **Merchandise > Price Books**.
1. Click a price book.
1. Click **Add SKUs**.
1. In the **Add SKUs** field, do one of the following:

    - Enter the SKU number and search for the product you want to add.
    - Select a product from the list.

1. Click **+** in the product listing for the products you want to add. The products are added.
1. Enter the price for the product in the appropriate currency. You can add new currencies under **System** in [Store Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
1. Click **Save**.

## Creating and Using Price Modifiers

You must perform the following steps to use price modifiers.

1. Create your price modifier.
1. Apply your price modifier to your product options.

### Creating price modifiers

To create a price modifier:

1. Go to **Merchandise > Price Books**.
1. Click the price book where you want to create your price modifiers.
1. Click **Price Modifiers**.
1. Click **Create New Price Modifier**.
1. From **Price Modifier Type** drop-down list, select either:

    - **Increment** to increase the price of your child products.
    - **Decrement** to decrease the price of your child products.

1. In **Name**, type a name for your price modifier. You must give the price modifier a unique name, for example, **tax_modifier**.
1. We recommend that you select **Copy** to copy the name of the product modifier. This is because you must make sure the price modifier name that you use matches exactly with the price modifier name you specified when creating your price modifier.
1. The currencies you have configured for Commerce Manager are displayed. For each currency, type the amount to modify the base product price by. You can add currencies to Commerce Manager in **Settings** > **Currencies**.
1. Click **Save**.

### Applying price modifiers

To apply a price modifier to a product option:

1. Go to **Merchandise > Products > Variations**.
1. Click **Variations**.
1. Click the variation whose options you want to apply a price modifier to.
1. Click **Options**.
1. In **Actions**, click **...** next to the option you want to apply a price modifier to.
1. From the menu, select **Edit Modifiers**.
1. From the **Modifier** drop-down list, select **price**.
1. In the **Price Modifier Name** field, type or paste the name of the price modifier you want to use. Make sure the price modifier name you use matches exactly the price modifier name you specified when creating your price modifier.
1. Click **Save**. You can edit and delete a price modifier at anytime. See [Variations, Options, and Modifiers](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products).

## Updating price books and prices

You can update product SKUs and prices.

1. Go to **Merchandise > Price Books**.
1. Do one of the following:

    - Click a price book.
    - Click **...** next to the price book you want to edit and click **Edit**.

1. Click **Add SKUs** to add more products to the price book.
1. In the **Add SKUs** field, do one of the following:

    - Enter a SKU and search for a product.
    - Select a product from the list.

1. Click **+** for the products you want to add.
1. To amend a product's price:

   1. Find the product whose price you want to update. In **Search**, you can search for a product SKU.
   1. (Optional) In **SKU**, click the field to update a product SKU.
   1. In *Currency*, where *currency* is the currency of the price you want to update, click the field to update the price.
   1. (Optional) Turn on the **Include tax** toggle if you want the price to include tax.

1. To delete a product, in **Actions**, click the trash can next to the product you want to delete.
1. Click **Save**.

## Deleting Price Books

Deleting a price book deletes the product prices in the price book. However, it does not delete the products. The pricing details in the orders referring to the deleted price book are also not deleted.

1. To delete a price book, in the **Merchandise > Price Books** page, do one of the following:

    - Click **...** next to the price book you want to delete and click **Delete**.
    - Select the checkbox of the price book you want to delete and click **Actions > Delete**.

1. To delete more than one price book, select the checkboxes of the price books that you want to delete and click **Actions > Delete**.

## Related Resources

- [Products](/docs/commerce-manager/product-experience-manager/products/overview)
- [Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/creating-catalogs)
- [Catalog Rules](/docs/commerce-manager/product-experience-manager/catalogs/catalog-rules)

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/oqdkiiMTN4s"
  mediaType="embed"
  title="Understanding Price Books" />
<Video
  mediaSrc="https://www.youtube.com/embed/5FbnzyNR1-w"
  mediaType="embed"
  title="Configuring Price Books in Commerce Manager" />
<Video
  mediaSrc="https://www.youtube.com/embed/diC3CeCTChU"
  mediaType="embed"
  title="Configuring Price Modifiers in Commerce Manager" />

---

## Files(Product-assets)

You can manage files on the **Merchandise > Media** page.

This page shows all files associated with your store, including image files for products. The list displays the name, ID, date created, file size, and MIME-type of each file.

The supported upload file type formats are:

- .jpg, .jpeg, .png, .gif, .mov
- .mpg .mp4, .mp3, .aac
- .vrml, .vr
- .doc(x), ppt(x), xls(x), pdf

By default, the maximum file size is 8 Megabytes. If you need to support larger file sizes, contact your Elastic Path representative.

Delete files by selecting the Trash can icon next to the listing.

To change the file or files associated with a product, see [Create Product-File Relationships](/docs/api/pxm/products/create-product-file-relationships).

---

## Export Products(Product-export)

If you want to modify product attributes, export the products in Commerce Manager. This builds a [Comma Separated Values (CSV)](/docs/api/pxm/products/product-export#product-export-csv-file) file containing the product entries, main image files, and custom extension data.

Each row in a `.csv` file represents a product. A `.csv` file can contain up to 50,000 products. If you want to export more than 50,000 products, you must have a separate `.csv` file and export products to each `.csv` file, one at a time.

After the file is exported, you get a link to the location where the `.csv` file is stored. Then you can make changes to the product fields (modify product information, add main image files, and custom extension data) using product import. For more information, see [Import Products Overview](/docs/commerce-manager/product-experience-manager/product-import/product-importer).

1. On the **All Products** page, select the checkboxes next to the products that you want to modify. You may apply appropriate filters to select the products.
2. Click the arrow next to the checkbox on the header row and then click **Export Products**.

![Export Products in Commerce Manager](/assets/export-products-cm.png)
    The **Export Confirmation** window appears.

3. Click **Export**.

---

## Importing and Updating Products

import Video from "/src/components/CardDisplay/video"

Product import uses a Comma Separated Values (CSV) file to import products, main image files and custom extension data. The structure of this file is defined in the [APIs docs](/docs/api/pxm/products/product-import-bulk-update).

You can use product import to:

- update existing products, including images, templates/flow fields and entries. The entry in the `.csv` file must have a unique `id` and/or `external_ref` that matches the `id` and `external_ref` of the existing product you want to update. You may have both a unique `id` and `external_ref`, but you must have at least one.
- Add new products, including new images, templates/flow fields and entries. For new products that you want to add, the entry in the `.csv` file must have an `external_ref` that does not match any existing products.

You cannot use product import to:

- Delete existing products.
- Import product bundles.

Each row in a `.csv` file represents a product you want to create/update. Each file can have 50,000 rows, including the header. If a CSV file exceeds 50,000 rows, an error is displayed, and the products are not imported.

A `.csv` file must not be larger than 50 megabytes. If a `.csv` file is larger than 50 megabytes, a `503 client read error` is displayed.

If you want to create/update more than 50,000 products or your `.csv` file is larger than 50 megabytes, you must have a separate `.csv` file and import each `.csv` file one at a time.

To import products:

1. Go to **Merchandise > All Products**.
1. Click **Product Imports** tab.
1. In **Import File**, click **Choose File**.
1. Browse to the location of your [Comma Separated Values (CSV)](/docs/api/pxm/products/product-import-bulk-update) file.
1. Select your CSV file and click **Open**. A notification indicating whether the operation is successful is displayed. The imported product information is displayed in the **All Products** tab.

## Demo

<Video
  mediaSrc="https://www.youtube.com/embed/lsWQ9M1-haE"
  mediaType="embed"
  title="Importing your products to Commerce" />

---

## Adding Product Details

1. (Optional) In **Locale**, select a language to use to localize product names and descriptions when creating your products. See [Configuring Locales](/docs/commerce-manager/product-experience-manager/products/configure-locales).
1. In **Name**: Enter a name for the product.
1. (Optional) **Description**: A description of the product. You can select:

    - **Plain text** - Use **Plain text** if you want your descriptions in plain text or if you want your descriptions to contain HTML tags. 
    - **Formatted** - Use **Formatted** to use our rich text editor when formatting your descriptions. You must only use the formatting options provided. No other HTML tags are supported. If you do provide descriptions that contain HTML tags, the HTML is reformatted to match the formats supported by our rich text editor. If you want your descriptions to contain HTML tags, you must use **Plain text**.

    ![Wysiwyg](/assets/wysiwyg5.gif)
 
1. Turn the **Product Status** toggle on to make the product `live`. Only products with a `live` status are published in catalogs. 
1. Turn the **Product Bundle** toggle on to make this product a bundle. See [Bundles in Commerce Manager](/docs/commerce-manager/product-experience-manager/bundles/bundle-configuration).
1. **SKU Number**: The SKU number of the product.
1. **Slug**: A label for the product that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. No spaces or other characters are allowed. By default, the product name is used as the slug.
1. **Commodity Type**: Whether the product is physical or digital.
1. (Optional) **MPN**: Manufacture Part Number (MPN).
1. (Optional) **UPC/EAN**: Universal Product Code (UPC) or European Article Number (EAN) used to scan a product in a Point of Sale (POS) system.
1. (Optional) **External Reference**: A unique attribute associated with the product. This could be an external reference from a separate company system, for example. The maximum length is 2048 characters.
1. Click **Next**.

---

## Adding Templates to Products

import Video from "/src/components/CardDisplay/video"

Ensure that at least one template is available.

1. In the **Product Templates** tab, click **Add Templates**. The [templates] available for the product are listed.
1. To add a template to the product, click **+** next to the template you want to add.

    - All templates added to the product are displayed in the **Templates list** table. This page also provides details of the templates, such as the name and values of the attributes in the templates.
    - You may have products with multiple templates, with each template having multiple attributes. You can select **Hide Empty Fields** to only view the fields that have values set.

1. Click **Next** or **Save & Exit**.

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/NY9D_aKfHGc"
  mediaType="embed"
  title="Configuring Templates and Attributes for Products" />

---

## Configuring Locales

You can localize product names and descriptions when creating your products.

By default, there are a number of language codes available. You activate locales in Commerce Manager in [**SYSTEM** > **Store Settings** > **Locales**]( /docs/commerce-manager/product-experience-manager/locales/). You can activate a maximum of five languages.

You can also add your own custom language codes if the language that you want to use is not available in [**SYSTEM** > **Store Settings** > **Locales**]( /docs/commerce-manager/product-experience-manager/locales/). You can do this using the [create a product](/docs/api/pxm/products/create-product) API request. Locales that are added using the [Create a product](/docs/api/pxm/products/create-product) API request are available in Commerce Manager under **Custom Product Locales**.

1. In the **Product Details** tab, expand **Locale** drop-down list. The languages you have activated in [**SYSTEM** > **Store Settings** > **Locale**]( /docs/commerce-manager/product-experience-manager/locales/) are displayed.
1. Select the language you want to use. If the language you want is not available, perform the following steps.

    1. Go to **SETTINGS** > **Locales** to find and activate the language you want.
    1. If the language you want is not shown in **SYSTEM** > **Store Settings** > **Locales** then add a custom locale using [create a product](/docs/api/pxm/products/create-product).

       :::caution
       If you add locales using [create a product](/docs/api/pxm/products/create-product) API request.

         - Locales created using this API request are not displayed in Commerce Manager.
         - The localized product names and descriptions for products created using this API request cannot be edited in Commerce Manager. You must update localized product names and descriptions using [update a product](/docs/api/pxm/products/update-product) API request.

       :::

1. Commerce Manager prompts you to enter the product name and description in the language you selected.
1. Type a localized name and description. A flag representing the language you are currently using is displayed.
1. When you have finished, select **Global** from the **Locale** drop-down list to return to **Product Details**. Commerce Manager shows you which localizations are being used for this product.
![Locales](/assets/locales2.png)
1. Repeat these steps for each language you want to use.
1. You can go back and edit any localized names and descriptions at any time by selecting the language you want from the **Locale** drop-down list.

---

## Configuring Product Price

import Video from "/src/components/CardDisplay/video"

Use this procedure to configure product pricing details, such as price books associated with the product, sale price and volume price, for a product. You can use volume pricing feature to set a different unit price for the product when shoppers make volume purchase of the product. You can select a price book for the product pricing and specify the new unit price offered when a minimum specified quantity is bought.

You can use the sale price feature and enable selling the product for a sale price during a specific period.

## Procedure

1. In the **Pricing > Price Books** tab:

    1. To associate the product with a price book, in the **Select Price Book** field, select a price book.
    2. Enter the amount in the available currencies.

          You can configure currencies in [Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
    3. Click **Save**.

1. If you want to add volume pricing or bundle sale pricing, expand **Advanced Pricing**.

    1. Click **Add Volume Level**.
    1. In **Price Book**, select the price book you want from the drop-down list.
    1. In **Min Purchase Quantity**, type the minimum quantity of products a customer must select to receive the volume price.
    1. Type a price for each of the available currencies. You can add currencies to a store under **System** in [Store Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
    1. Click **Add Level**.

    :::note Volume Pricing Limitation
    Volume pricing applies to standalone products and fixed-price bundles (the bundle as a whole). Volume pricing does not apply to individual products when they are used as components within bundles.
    :::

1. To add a sale price, click **+ Add Sale Price** and do the following:

    1. To associate the option with a price book, from **Price Book** list, select a price book.
    1. In **Sale Name**, type a name for your sale. For more information, see [Price books](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks).
    1. From **Start Date / Time - End Date / Time**, click **Start date** to display the calendar. 
    1. Use the calendar to select a start date and time. 
    1. Click **OK**.
    1. Use the calendar to select an end date and time.
    1. Type a price for each of the available currencies. You can add currencies under **System** in [Store Settings > Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
    1. Click **Add Sale**.

    :::tip
    Both list and sale price (or was/is prices) are available in the catalog response, enabling you to display slash pricing on your storefront, depending on your requirements.
    ![Custom](/assets/sale-price.png)
    :::

1. Click **Next** or **Save & Exit**.

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/oqdkiiMTN4s"
  mediaType="embed"
  title="Understanding Price Books in Product Content Management" />
<Video
  mediaSrc="https://www.youtube.com/embed/heuLtuYZ1Wc"
  mediaType="embed"
  title="Sale Price Configuration" />

---

## Creating Products

import Video from "/src/components/CardDisplay/video"

# Prerequisite

- Ensure that you have [created at least one price book](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks#creating-price-books).

## Best practices

- [Create at least one template with attributes](/docs/commerce-manager/product-experience-manager/products/add-product-templates) before creating a product.
- [Create at least one variation with options and required modifiers to build child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products) before creating a product.

The following steps provide a high-level procedure to complete a product configuration:

1. In the **Merchandise > All Products** page, click **Create New**.
1. In the [**Product Details**](/docs/commerce-manager/product-experience-manager/products/add-product-details) tab, enter the product details.
1. You can allow your shoppers to add custom text to a product if you have products, like T-shirts or greeting cards that can be printed with your shoppers [personalized messages](/docs/commerce-manager/product-experience-manager/products/personalizing-products).
1. In the **Product Templates** tab, add [templates](/docs/commerce-manager/product-experience-manager/products/add-product-templates) for the product.
1. In the **Pricing** tab, configure the [pricing settings](/docs/commerce-manager/product-experience-manager/products/configure-product-price) for the product.
1. In the **Variations** tab, associate [variations](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products) with the product and [build child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products) with the variations and options.
1. In the **Inventory** tab, [manage the product inventory](/docs/commerce-manager/product-experience-manager/products/configure-product-price).
1. In the **Media Management** tab, upload the [product images](/docs/commerce-manager/product-experience-manager/products/manage-product-media).

You can use **Back** and **Next** buttons to navigate through the tabs and the **Save & Exit** button to save the changes and exit the window any time.

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/CPxjjdOmWhM"
  mediaType="embed"
  title="Configuring a Product" />

---

## Curating Products

You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront. Having unique product collections means you can appeal to niche customer bases, driving increased customer engagement and sales. For example, you may find you have an abundance of cotton T-Shirts and you want to promote these products to the top of the product list. When a shopper navigates to **T-shirts**, the cotton T-Shirts are displayed first.  You can only curate 20 products or less. You cannot have more than 20 curated products.

1. Go to Product Experience Manager. You can either:

    - Select **Products** > **All Products**.
    - Select **Configurations** > **Hierarchies** and select the hierarchy that contains the node whose products you want to curate. 

1. Navigate to the node whose products you want to curate.
1. Select the pin against the product you want to curate. Each time you select a pin, the product whose pin you selected moves to the top of the list.  

![curated products](/assets/curated_products.png)

---

## Deleting Products

Deleting a product removes the product information and the associated media files from the database. However, the product references are not deleted from the price books that consist of the product information. You must republish the catalog to update the catalog release with the changes. If you want to keep your hierarchies and price books up to date, remove the deleted products from those resources.

Even after deleting a product, an order history that has the product still keeps the product information of the deleted product, such as, the product SKU, product ID, and price. However, clicking the product does not take a shopper to the product details.

To delete a product, in the **Merchandise > All Products** page, click **...** and click **Delete**.

:::tip
To remove products from the catalog and still keep them in the database for audit purposes, set the product status to draft instead of deleting it. Additionally, remove the product from hierarchies, and republish the affected catalogs so that it does not appear in the storefront.
:::

---

## Editing Products

After editing a product, ensure that you republish all catalogs that contain the product to reflect the changes.

1. In the **Merchandise > All Products** page, do one of the following:

    - Click on the product or Click the **...** icon and click **Edit**.
    - You may have products with multiple templates, with each template having multiple attributes. You can select **Hide Empty Fields** to only view the fields that have values set.

1. Update the details as required.

    For the changes to appear in the store, republish the catalogs that contains hierarchies with this product.

---

## Filtering Products

You can filter your products. The filter options that are available depend on the attribute you have chosen to filter your products on.

## Filter Characteristics

Filters in Commerce Manager have the following characteristics.

- You can configure more than one filter at a time. For example, you may want to find all products whose name start with **T-Shirt** and whose SKU is like **287**. A chain of filters must not exceed 10 filters.
- Filters  must not exceed 8KB.  This is equal to approximately, for example, 200 IDs when using a `list` filter.

![filter restriction](/assets/filter_restriction.png)

- Filtering in Commerce Manager is case-sensitive. However, filtering on SKU is not case-sensitive.
- Filters do not work with attributes that contain commas. For example, filtering on this product name does not return any products:

  ![attribute with comma](/assets/comma_filter.png)

## List Filter Characteristics

The **list** filter has the following characteristics.

- You cannot apply other filters with a **list** filter. The following error message is displayed:

  ![list filter error](/assets/list_filter_error.png)

- When providing a list, you can separate the items in the list.

    - (default) **Spaces**
    - **Line breaks**
    - **Comma separated**
    - **View as tags**

    The separator you choose depends on your requirements. For example, when using the **list** filter for product name in the following scenario:

    - Product names contain spaces.
    - There is more than one product with the same name.

    you should use **Comma separated** instead of **Spaces**.

  ![list filter separator example](/assets/list_seperator.png)

:::tip
Filter query parameters are available in the URL. Bookmark your filter URL to automatically activate that filter without having to reapply the filter each time.
:::

## Supported Characters

The following table describes the supported characters that can be used in filters.

| Characters                 | Can be used in filter?                 |
|:---------------------------|:---------------------------------------|
| `A-Z` (upper & lower case) | Yes                                    |
| `0-9`                      | Yes                                    |
| `$` `-` `_` `*` `.`        | Yes                                    |
| " " (space)                | Yes (a`+` is also treated as a space). |

## Supported Date Formats

If you need to specify a date, specify the date in `YYYY-MM-DD` format, for example 2022-04-27. You can also specify the
date as an integer number of milliseconds since 1970-01-01 00:00:00. This is also known as UNIX time. For example,
`640912546584`.

## Filter Options

The following table describes the filter options available for each attribute.

| Attribute           | Filter                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|---------------------|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ID                  | **is****list**                                                                   | For **is**, type the value you want. You can use [supported characters](#supported-characters).For **list**, specify a list of IDs. Only the products whose IDs you have specified are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Name                | **starts with****is****is like****ends with****list** | For **starts with**, **is**, **is like**, and **ends with**, type the value you want. You can use [supported characters](#supported-characters).For **list**, specify a list of names. Only the products whose names you have specified are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| SKU                 | **starts with****is****is like****ends with****list** | For **starts with**, **is**, **is like**, and **ends with**, type the value you want. You can use [supported characters](#supported-characters).For **list**, specify a list of SKUs. Only the products whose SKUs you have specified are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Description         | **starts with****is****is like****ends with**                  | Type the value that you want. You can use [supported characters](#supported-characters).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Slug                | **starts with****is****is like****ends with****list** | For **starts with**, **is**, **is like**, and **ends with**, type the value you want. You can use [supported characters](#supported-characters).For **list**, specify a list of slug. Only the products whose slugs you have specified are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Commodity Type      | **Physical****Digital**                                                          | Select  **Physical** or **Digital** to display a list of physical or digital products.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| UPC/EAN             | **starts with****is****is like****ends with****list** | For **starts with**, **is**, **is like**, and **ends with**, type the value you want. You can use [supported characters](#supported-characters).For **list**, specify a list of UPC/EANs. Only the products whose UPC/EANs you have specified are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| MPN                 | **starts with****is****is like****ends with****list** | For **starts with**, **is**, **is like**, and **ends with**, type the value you want. You can use [supported characters](#supported-characters).For **list**, specify a list of MPNs. Only the products whose MPNs you have specified are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Status              | **Live****Draft**                                                                | Select **Live** or **Draft** to display a list of live or draft products.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Templates           | **is****list**                                                                   | Use this filter to filter template attributes. Select a template from the list.In **Attributes**, select an attribute from the list. (Attributes with a `date` type are not displayed because Commerce Manager does not support filtering on template attributes with a `date` type.) The filter operators are displayed.Select **is** or **list**. The **list** filter option does not support `integer`, `float`, or `boolean` attributes, hence no filter operators are displayed for attributes of these types.Enter the values you want to search for.You can chain filters to search for more than one template attribute at a time.                                                                                                                                                                                                                                                                           |
| Owner               | **Organization****Store**                                                        | Select **Organization** or **Store** to display a list of organization or store products.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Has Node Assignment | **False**                                                                                                   | Use this filter to find orphaned products. Products must be assigned to nodes to be included in a catalog. **Note**: You cannot use this filter to show products that *are* assigned to nodes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| External Reference  | **starts with****is****is like****ends with****list** | For **starts with**, **is**, **is like**, and **ends with**, type the value you want. You can use [supported characters](#supported-characters).  External references have a maximum length of 2048 characters.For **list**, specify a list of external references. Only the products whose external references you have specified are displayed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Product Types       | **is****list**                                                                   | For **is**, enter the product type you want.For **list**, specify a list of product types. Only those product types are displayed.`standard` - A standard product is a standalone product.`parent` - A parent product is a product that has child products that have been built in Commerce Manager. See [Assigning Variations and Building Child Product](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products).`child` -  When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.`bundle` - A bundle is a purchasable product, comprising one or more standalone products (in other words, `components`) to be sold together. See [Bundle Components and Options](/docs/commerce-manager/product-experience-manager/bundles/bundle-configuration#bundle-components-and-options). |

## Creating Filters

The following steps describe how to create a filter.

1. Go to **Merchandise > All Products** page.
1. Click **Filters**.
1. From the list, select the attributes you want to filter your products on. The filter options are displayed. The options that display depend on the attributes you have selected.
1. Configure your filter. See [Filter Options](#filter-options).
1. Once you have configured your filter, either:

   - Press **Enter** to automatically apply your filter.
   - Click **Apply Filters**.

    Commerce Manager displays the number of products that match your filter.

![Product Filtering](/assets/cm_filtering.gif)

1. Your filters are retained even when you navigate away from the filter results. You can remove your filters at any time by, either, removing an individual filter or, clicking **Clear All**.

---

## Managing Product Inventory

import Video from "/src/components/CardDisplay/video"

Inventory is the quantity of each product that you have in stock.

1. In the **Inventory** tab, click **Manage inventory**.

    The following details are displayed:

    - **Product Name**
    - **SKU**
    - **In stock**
    - **Allocated**: The amount of reserved product in stock.
    - **Available**: The amount of product available in the stock minus allocated product. (Available = Total - Allocated).
1. In the **Manage inventory > Actions** field, select one of the following options, and in the **Qty** field, enter the appropriate quantity:

    - **Allocate** : Reserves a number of inventory items so that you cannot sell the allocated items.
    - **Deallocate** : Reduces the number of allocated items so that you can sell the items again.
    - **Increment** : Adds stock to the total inventory.
    - **Decrement** : Reduces the specified quantity from the total inventory.

    After you update the stock, the activity is added to the log and the **Inventory log** tab displays the details of each activity.
1. Click **Next** or **Save & Exit**.

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/HlQd5lvGqVU"
  mediaType="embed"
  title="Configuring Inventory" />

---

## Managing Product Media

Products can have rich media assets, such as product images or a file containing additional product details.

1. To add media to a product, in the **Media Management** tab, do one of the following:

    - Drag and drop the file from your local directory.
    - Click **Choose File** and browse and add the file.
    - In the **add by URL** field, add the URL for the media.
1. Click **Done**. You can add multiple media for a product. All media that you upload are listed in the **Media upload** table.
1. To assign an image as the main image for a product, select the **Use as main image** field next to the image name.
1. Click **Next** or **Save & Exit**.
1. To delete media from Commerce, go to **Products** > **Media**. See **Files** in [Media](/docs/commerce-manager/product-experience-manager/product-assets/files).

---

## Overview(Products)

import Video from "/src/components/CardDisplay/video"

import Overview from "../../../partials/pxm/products/productsoverview.mdx";
import ProductTypes from '/docs/partials/pxm/products/types.mdx';
import ProductCatalogs from '/docs/partials/pxm/products/catalogs.mdx';

<Overview></Overview>

### Product Types
      
<ProductTypes> </ProductTypes>

### Products and Catalog Releases

<ProductCatalogs> </ProductCatalogs>

- See the nodes that products belong to.

![product tabs](/assets/product-tabs-gifs.gif)

- Create nodes and assign products to nodes.

![assign products](/assets/assign_node.gif)

## Related Resources

- [Product Templates](/docs/commerce-manager/product-experience-manager/products/add-product-templates)
- [Product Attributes](/docs/commerce-manager/product-experience-manager/extending-products/templates)
- [Product Hierarchies](/docs/commerce-manager/product-experience-manager/hierarchies/overview)
- [Variations](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products)
- [Price books](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/SdaSEgA5rTc"
  mediaType="embed"
  title="Understanding Products in Product Experience Manager" />
<Video
  mediaSrc="https://www.youtube.com/embed/_VoXvL9qKPo"
  mediaType="embed"
  title="Product and Hierarchy Management" />

---

## Personalizing Products

import PersonalProducts from '/docs/partials/pxm/products/personalizing.mdx';

<PersonalProducts></PersonalProducts>

1. Go to**Merchandise > All Products** page
2. From **All Products**, navigate to the product you want to personalize.
3. Select the product to edit it.
4. Expand **Personalization**.
5. Select **New Custom Input**.
6. Configure the following fields:

   | Field            | Required  | Description                                                                                                                  |
   |------------------|-----------|------------------------------------------------------------------------------------------------------------------------------|
   | **Custom Input Key** | Required  | Enter a name for the custom input field, for example,  **Front** or **Back**.                                                |
   | **Custom Input Name** | Optional | Enter a descriptive name for the type of custom text a shopper can add, for example, **T-Shirt Front**, or **T-Shirt Back**. |
   | **Maximum length**   | Optional | You can add a maximum length. For example, the input field must be  50 characters in length. The limit is 255 characters.    |
   | **Required Input**   | Optional | Toggle **Required Input** on if a shopper must specify some personalization text.   |

![personalization in CM](/assets/personalized-cm.png)

7. Select **Save & Exit** or **Next**, depending on your requirements.

---

## Relating a Product to one or many Products

import CardDisplay from "/src/components/CardDisplay";

<grid>
  <CardDisplay
    mediaSrc="https://share.vidyard.com/watch/T2pVQwpEz8o9iSz1zxiLzP?"
    mediaType="embed"
    title=""
    description="Creating Custom Product Relationships"
  />
</grid>

## Related Resources

- [Custom Relationships](/guides/key-concepts/product-experience-manager/custom-relationships/)
- [Creating Upsell Product Relationships](/guides/How-To/Products/up-selling-pxm)
- [Creating Cross-sell Product Relationships](/guides/How-To/Products/cross-selling-pxm)
- [Create a Custom Relationship API Reference](/docs/api/pxm/products/create-custom-relationship)
- [Associate a Product to other Products API Reference](/docs/api/pxm/products/product-association-id)

---

## Searching for Products

You can search products using a product's attributes. The products that contain the criteria you have entered are automatically displayed.

:::caution
Searching in Commerce Manager is case-sensitive.
:::

1. Go to **Merchandise > All Products** page
1. By default, **SKU** is selected. Click **SKU** to display a list.
1. From the list, select either:

    - **SKU**
    - **Name**
    - **Slug**
    - **UPC/EAN**
    - **MPN**
    - **Description**

1. From the list, select either:

    - **starts with**. Matches the products whose attributes start with the criteria you have typed.
    - **is**. Matches the product whose attributes are exactly the same as the criteria you have typed.
    - **is like**. Matches the products whose attributes are similar to the criteria you have typed.
    - **ends with**. Matches the products whose attributes end with the criteria you have typed.

1. In the **Find product** box, enter your search criteria.
1. Click **Search**.

---

## Subscription Products

Elastic Path Subscriptions allows you to offer your customers subscriptions and recurring billing for your products and services. Elastic Path Subscriptions gives you the flexibility to pause, update, or reactivate your subscription offerings, change subscription cycles and apply discounts.

You can build subscription offerings with products created in Product Experience Manager. Product Experience Manager manages product information, hierarchies, and price books. Ideally, Product Experience Manager becomes the single source of truth for product data across your organization.

## Prerequisites

You must create all of your currencies in your store. See [Manage Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).

## Creating a Subscription Product

The following steps describe how to create a subscription product in Product Experience Manager.

:::note
When creating a product in Product Experience Manager for a subscription, you can only create new offerings. You cannot add your Product Experience Manager product to an existing offering.
:::

1. Log in to Commerce Manager.
2. Go to **Merchandise > All Products** page
3. Select **Create New**.
4. Follow the instructions described in [Creating Products](/docs/commerce-manager/product-experience-manager/products/create-products) to create your product.
5. Select the **Subscriptions** tab.
6. Select **Create New Offering**.
7. Follow the instructions described in [Creating Offerings](/docs/commerce-manager/subscriptions/offerings/creating-offerings) to create your offering.
8. You must select **Save** for your changes to take effect. If you select **Save & Exit** before selecting **Save**, your changes are lost.

![PXM Subscription product](/assets/subscription_pxm.png)

9. Select **Save & Exit** or **Next** depending on your requirements.
10. You can edit a product or service at any time by selecting **...** > **Edit** on the product you want to edit.

---

## Tagging Products

import ProductTags from "../../../partials/pxm/products/tags.mdx";

<ProductTags></ProductTags>

The following steps describe how to create product tags.

1. Go to **Merchandise > All Products** page
1. Navigate to the product you want to tag.
    - You can have up to 20 tags per product.
    - Each tag can be up to 255 characters long.
1. In **Product Tags**, either:
   - enter a tag and press **Enter**. Repeat this step for each tag you want to use.
   - select **View as a comma separated list** and enter a comma separated list of tags.

    ![product tags](/assets/product_tags.png)

1. Depending on your requirements, select either **Save & Exit** or **Next**.

---

## Viewing Product Details

You can view your products in **Merchandise > All Products** page.

The following details are displayed:

| Name | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| --- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Name** | The name of the product.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **SKU** | The unique stock keeping unit of the product.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Type** | Whether the product type is: **Product** - a parent product. See [Assigning Variations and Building Child Products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products).**Bundle** - a product bundle. See [Bundles in Commerce Manager](/docs/commerce-manager/product-experience-manager/bundles/bundle-configuration).**Child** - a child product. See See [Assigning Variations and Building Child Products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products). |
| **Status** | The product status. **Draft****Live** - Only products with a **live** status are published in catalogs.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **Created** | The date and time a product is created.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Updated** | The date and time a product was last updated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

---

## Assigning Variations and Building Child Products

import Video from "/src/components/CardDisplay/video"

Product variations are the options available for a parent product that your shoppers can choose, such as different sizes, colors, materials, or any other specific features. You can create and manage up to 10,000 unique combinations of options for variations of a product. You can then use catalogs to build different catalogs for different users, giving you greater flexibility with your product data and making it easier for your shoppers to interact with your products.

## Reusability

Variations are reusable, and you can associate the same variation to any number of products. The following scenario provides an example:

1. Create a variation `shoe size` and add five options in the variation.
1. Create a product `shoe 1` and associate the variation `shoe size` to the product.
1. Create second product, `shoe 2` and associate the variation `shoe size` to this product as well.
1. Create a third product `shoe 3` and do not associate any variations to this product.

`shoe 1` and `shoe 2` inherit the properties of the `shoe size` variation, and you can build the child products with the options. However, you cannot build child products for `shoe 3` unless you assign a variation with at least one option to the product.

## Including/Excluding Variation Options When Building Child Products

When building your child products, you can choose to exclude or include variation options. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Selection Variation Options](#selecting-variation-options).

## Prerequisites

Before assigning variations to your products:

- Ensure that one variation with at least one option is available.
- Ensure that variation and option names:

    - Contain only uppercase and lower case letters.
    - Contain digits from 0 to 9, underscore (_), or hyphen (-).
    - Do not contain any other special characters.

    You can build the child products only if all variations and the options are named appropriately. See [Creating Variations and Options](/docs/commerce-manager/product-experience-manager/variations/).

- (Optional) In addition, for each option you can configure product and price modifiers. See [Creating Product Modifiers](/docs/commerce-manager/product-experience-manager/variations/).

## Assigning Variations

To assign variations to a product:

1. Go to **Merchandise > All Products** page. You can assign variations and build child products when you are creating a new product or for an existing product.
1. Once you are viewing a product, select the **Variations** tab.
1. Select **Associate Variation**.
1. Expand **Add Variation** to display a list of available variations. You must associate variations one at a time.
1. Select a variation. All options within the selected variation are displayed in the **Variation Options** field.
1. Select **Associate to Product**.
1. Repeat steps 2 - 6 to assign all required variations to the product.

## Including/Excluding Variation Options

When building your child products, you can choose to exclude or include variation options. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy.

:::caution
You cannot configure a combination of inclusions and exclusions. In other words, you cannot include all small, medium, red, and blue t-shirts, apart from small, red t-shirts.
:::

Configure **Option Combination Rules** to specify variation options to include or exclude when building your child products. The following example builds all t-shirt variations apart from large, red, t-shirts.

![exclusions](/assets/exclusions.png)

To configure **Option Combination Rules**:

1. Expand **Option Combination Rules**.
1. Select:

    - **Include** if you want to include specific variation options. For example, you may want none of your variation options to be built apart from medium, blue t-shirts.
    - **Exclude** if you want to exclude specific variation options. For example, you may want all your t-shirt variation options to be built apart from large, red t-shirts.

1. Select **Add Inclusion** or **Add Exclusion** depending on whether you selected **Include** or **Exclude**. The variations associated with this product are displayed.

![option combination](/assets/option_combination.png)

1. Select the variation you want. The options available for the variation are displayed.
1. Select the option that you want.
1. Select **OK**.
1. Repeat steps 2 - 6 to add more variation options.
1.  Select **Build Child Products** to build your child products or save your inclusions/exclusions and build your child products later.

## Building Child products

Child products are generated by combining the variations and the options within each variation. For example, if you assign the following variations for the product, **T-Shirt**:

| Variation | Option               |
|:----------|:---------------------|
| size      | small, medium, large |
| color     | green, blue, red     |

When you build the child products, products with the following SKU are created:

![Child products](/assets/build-child-product.png)

To build your child products:

1. Select **Build Child Products** to build your child products. If you click **Build Child Products** without assigning a variation to the product, a message prompting you to select a variation is displayed.
1. Once your have built your child products, expand **Child Products** to see a list of your child products. The child products are indicated with the **Child** type.

 After updating or deleting variations and options, you must rebuild the child products for the changes to take effect.

- From **Option Combination Rules**, select **Build Child Products**.

  :::note
  If you have edited your inclusions/exclusions but not yet saved your changes, selecting this button saves your changes and then builds your child products.
  :::

- Expand **Child Products** and select **Rebuild Child Products**.

## Demos

<Video
  mediaSrc="https://www.youtube.com/embed/a1mSUDAxx7k"
  mediaType="embed"
  title="Create Variations and Options" />

---

## Product Variations, Options, and Modifiers

import Video from "/src/components/CardDisplay/video"

Product variations are the options available for a parent product that your shoppers can choose, such as different sizes, colors, materials, or any other specific features. You can create and manage up to 10,000 unique combinations of options for variations of a product. You can then use catalogs to build different catalogs for different users, giving you greater flexibility with your product data and making it easier for your shoppers to interact with your products.

For example, a product has two variations size and color. The size variation has three options, such as small, medium, and large and the color variation has three options, such as green, red, and blue. This creates a variation matrix with nine possible unique combinations or child products as shown in the following example:

![The sizes are across the top row and the colors are in the first column.](/assets/product-variations-1.png)

You can create additional variations or options and attach them to a product to increase the number of combinations. Using the previous example, if you add a third variation with three options, you can build child products with 27 unique combinations of variations and options.

## Reusability

Variations are reusable, and you can associate the same variation to any number of products. The following scenario provides an example:

1. Create a variation `shoe size` and add five options in the variation.
1. Create a product `shoe 1` and associate the variation `shoe size` to the product.
1. Create second product, `shoe 2` and associate the variation `shoe size` to this product as well.
1. Create a third product `shoe 3` and do not associate any variations to this product.

`shoe 1` and `shoe 2` inherit the properties of the `shoe size` variation, and you can build the child products with the options. However, you cannot build child products for `shoe 3` unless you assign a variation with at least one option to the product.

## Building Child Products

Child products inherit attributes from their parent products. When you make changes to the attributes of the parent products, you can rebuild your child products, ensuring that changes to the parent products are propagated to the child products.

Alternatively, you can modify a child product independently, without impacting its parent product. For example, you may prefer the status of your child product to be `live`, while keeping the parent product's status as `draft`. When you directly update a child product, it becomes independent of its parent product. In other words, any subsequent changes made to the parent product are not automatically reflected in the child product when you rebuild the parent product and its child products. Once a child product is independent of its parent, you cannot recreate the association between the child product and its parent. You must delete the child product and rebuild the parent to recreate the child product.

Following on from that, if you add the same flow to both a parent and child product, the child flow values are not affected by changes to the parent flow values in a rebuild.

In addition, when building your child products, you can choose to exclude or include certain combinations of variation options. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [Assigning Variations and Building Child Products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products).

## Sorting the Order of Variations and Options

When variation and variation products are built with a product, they can then be added to your catalogs.

By default, variations and variation options are sorted randomly. You can configure the **Sort Order** to sort the order of your variation and variation options. You can then use the **Sort Order** value to program your storefront to display the variations and variation options in the order that you want.

A **Sort Order** value must be a number. You can specify any numbers that you want.

- 1, 2, 3, or 100, 90, 80, and so on.
- Zero or negative numbers.

To no longer specify a sort order for variations and variation options, remove the sort order value from **Sort Order**.

:::caution
- Commerce Manager does not sort variation options. You must program your storefront to sort the variation options in the order that you want.
- You must rebuild your products for the sort order changes to take effect.
:::

## Product Modifiers

Use modifiers to change the properties of child products that are inherited from a product. With modifiers, you only need to have one product with a variation attached to the product.

Modifiers attached to a variation option are applied to a product to create child products. For example, instead of creating three  products for three different shirt colors, you can do the following:

1. Create a product, *shirt*, with the variation, *color*, attached to it.
1. Create three options for the *color* variation.
1. Create a modifier for each option to change the properties of each child product. For example, attach a *description append* modifier to each option so that each child product has a different description based on the color of the child product.
1. Build the child products.

Below is an example of a child product of **T-Shirt** whose description is **Red T-Shirt** because of a modifier for the **Red** option in the **Color** variation.

![Child products with different descriptions](/assets/modifier-description-append.png)

## Price Modifiers

You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their parent products. Using price modifiers, you can enable child products to inherit a different price. This enables you to configure the price of child products, for example, to be lower than its parent product, without having to individually update the price of your child products. There are three types of price modifier.

Modifier | Data Type | Effect |
| :--- | :--- | :--- |
| `price_increment` | `string` | Increases the price of a product. |
| `price_decrement` | `string` | Decreases the price of a product. |
| `price_equals` | `string` | Sets the price of a product to the amount you specify. |

The following is an overview of the steps you need to follow to use price modifiers.

1. Create a price modifier. You must give the price modifier a unique name, for example, tax_modifier. For more information, see [Create a Price Modifier](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks#creating-price-modifiers)
1. Create a product modifier that uses the same name as the price modifier. For more information, see [Create Modifiers](/docs/api/pxm/products/create-modifier).
1. Build your child products with the new product modifier. For more information, see [Build Child Products](/guides/How-To/Products/build-pxm-variations).

## Creating Variations, Options, & Modifiers: An Overview

Do the following to create variations, options, and modifiers:

1. [Create variations](#creating-variations-and-options).
1. For each variation, [create options](#creating-variations-and-options).
1. (Optional) For each option, [set modifiers](#creating-product-modifiers).
1. (Optional) Add price modifiers.
1. [Associate variations to products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products).
1. [Build child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products#building-child-products).

:::caution

- If no modifier exists for an option and you build child products using that option, the slug and SKU are autogenerated and appended to the slug and SKU of the child product.
- After updating variation, option, or modifiers, you must [rebuild the child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products#building-child-products) for the changes to take effect.

:::

## Creating Variations and Options

1. Go to **Merchandise > Products > Variations**.
1. Click the **Variations** tab.
1. Click **Add Variation**.
1. In the **Variation Name** field, enter a name.

    Use only letters, both uppercase and lower case, digits 0 to 9, underscore (_), or hyphen (-) in the name. Do not use any other special characters.
1. (Optional) In **Sort Order** specify a value to represent the order in which a variation should be displayed in a storefront. A **Sort Order** value must be a number. You can specify any numbers that you want.

    - 1, 2, 3, or 100, 90, 80, and so on.
    - Zero or negative numbers.

   To no longer specify a sort order for variations and variation options, remove the sort order value from **Sort Order**.

   :::caution
   Commerce Manager does not sort variations. You must program your storefront to sort the variation options in the order that you want.
   :::

1. Click **Next**.
1. Click **Add Variation Option** where *Variation* is the name of the variation you created above.
1. In the **Variation Name** field, enter the name of the option.

    Use only letters, both uppercase and lower case, digits 0 to 9, underscore (_), or hyphen (-) in the name. Do not use any other special characters.
1. In the **Variation Description** field, enter a description for the option.
1. (Optional) In **Sort Order** specify a value to represent the order in which a variation option should be displayed in a storefront. A **Sort Order** value must be a number. You can specify any numbers that you want.

   - 1, 2, 3, or 100, 90, 80, and so on.
   - Zero or negative numbers.

   To no longer specify a sort order for variations and variation options, remove the sort order value from **Sort Order**.

   :::caution
   Commerce Manager does not sort variation options. You must program your storefront to sort the variation options in the order that you want.
   :::
1. Click **Add option**.
1. To add more options, repeat steps 6 - 7.

If you update your variations and options for a product, you must [rebuild the child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products#building-child-products) for the changes to take effect.

### Deleting Variations

You can only delete the variations that are not in use. If you try to delete a variation that is still in use, a **One or more variations are currently in use** message is displayed.

If you still want to delete the variation, ensure that the variation is deleted from all products that use the variation.

1. Go to **Merchandise > Products > Variations**.
1. Click the **Variations** tab.
1. Click **...** next to the variation that you want to delete.
1. Click **Delete**.

    A warning message confirming the delete action is displayed.
1. Click **Delete**.

The variation and all options within the variation are deleted. You must [rebuild the child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products#building-child-products) for the product for the changes to take effect. When you rebuild the child products, all child products that contain the variation and options are also deleted.

### Deleting Options

To delete an option in a variation:

1. Go to **Merchandise > Products > Variations**.
1. Click the **Variations** tab.
1. Click the variation whose options you want to delete.
1. Click the **Options** tab.
1. Click **...** next to the option you want to delete and click **Delete Option**.

You must [rebuild the child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products) for the product for the changes to take effect. When you rebuild child products, all child products generated with this option are deleted from the store.

## Creating Product Modifiers

Modifiers are applied to the child products that are built using the variations and options for which modifiers are created. Modifier values can only contain A-Z, a-z, 0 to 9, -, and _. No spaces or special characters are allowed.

You cannot duplicate a modifier type and operation combination. However, you can add a different operation for the same modifier type. For example, you can only have one SKU builder modifier, but you can add another SKU append modifier to the same option.

To add modifiers to an option:

1. Go to **Merchandise > Products > Variations**.
1. Click the **Variations** tab.
1. Click a variation.
1. Click **Options**.
1. Click **...** next to the option that you want to add a modifier to and click **Edit Modifiers**.
1. The values you can set depend on the modifier you want to use.

    | Modifier | Description |
    | --- | --- |
    | SKU | Append - Adds the SKU you specified in **Value** to the end of the child product's SKU.Prepend - Adds the SKU you specified in **Value** to the beginning of the child product's SKU.Equals - Replaces the child product's SKU with the SKU you specified in **Value**.Builder - Replaces part of the child product's SKU. In **Seek**, specify the part of the child product's SKU you want to replace. In **Set**, enter the replacement SKU. |
    | Slug | Append - Adds the slug you specified in **Value** to the end of the child product's slug.Prepend - Adds the slug you specified in **Value** to the beginning of the child product's slug.Equals - Replaces the child product's slug with the slug you specified in **Value**.Builder - Replaces part of the child product's slug. In **Seek**, specify the part of the child product's slug you want to replace. In **Set**, enter the replacement SKU. |
    | Description | Append - Adds the description you specified in **Value** to the end of the child product's description.Prepend - Adds the description you specified in **Value** to the beginning of the child product's description.Equals - Replaces the child product's description with the slug you specified in **Value**. |
    | Name | Append - Adds the name you specified in **Value** to the end of the child product's name.Prepend - Adds the name you specified in **Value** to the beginning of the child product's name.Equals - Replaces the child product's name with the name you specified in **Value**. |
    | commodity_type | In **Value**, select either **physical** or **digital** to set the commodity type of the child product. |
    | Status |  In **Value**, select either **live** or **draft** to set the status of the child product. |
    | Price | In **Price Modifier Name**, type or paste the name of your price modifier. Make sure the price modifier name exactly matches the price modifier name you specified when creating your price modifier. See [Price Modifiers](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks#creating-and-using-price-modifiers). |

1. Click **Save**.
1. Click **Add another modifier** or click **Cancel** to exit.

### Deleting Product Modifiers

To delete a modifier:

1. Go to **Merchandise > Products > Variations**.
1. Click the **Variations** tab.
1. Click a variation.
1. Click the **Options** tab.
1. Click **...** next to the option that you want to delete and click **Delete Modifiers**. All modifiers added to the option are displayed.
1. To delete a modifier, click the **Delete** icon next to the **Value** field of that modifier.

You must [rebuild the child products](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products#building-child-products) for the product for the changes to take effect.

## Demo

<Video
  mediaSrc="https://www.youtube.com/embed/a1mSUDAxx7k"
  mediaType="embed"
  title="Create Variations and Options" />

---

## Creating a Promotion in Promotions Builder

## Creating a Promotion

1. Go to **Merchandise > Promotions > Builder**.
2. Click **New promotion**.
3. Enter a name for the promotion in the **Name** field.
4. Enter a description for the promotion in the **Description** field.
5. Select the start date in the **Start Date** field.
6. Select the end date in the **End Date** field.
7. (Optional) Enter the priority number in the **Assign a priority** field. This field determines the order of the stackable promotions that can be applied simultaneously. Each promotion must have a unique priority number. If you assign a priority number that is already in use by another promotion, you will receive an error message.
If a priority is not assigned, promotions will be applied in the order of their creation dates, with the newest promotions applied first and discounted prices calculated against any previously-discounted item prices.
8. Select the **Enabled** toggle to activate the promotion. It is disabled by default.
9. Select the **Stackable** toggle to allow multiple promotions to be stacked. This option is disabled by default and controls whether a promotion can be stacked with others. If this toggle is not enabled, no other promotion can stack on top. The promotion with the highest priority will take precedence. See [Stacking and Prioritizing](/docs/commerce-manager/promotions-builder/index?#stacking-and-prioritizing-multiple-promotions)
10. (Optional) Select the **Override stacking** toggle under **Advanced settings** to allow the promotion stack with other promotions that are typically non-stackable. Default is `false` when not set. When set to `true`, the promotion can stack with promotions configured as non-stackable, unless those non-stackable promotions also override stacking. See [Override Stacking](/docs/promotions-builder/overview?#override-stacking)
11. (Optional) Select the **Coupon-driven** toggle to manually [create a single code](/docs/commerce-manager/promotions-builder/creating-promotion-codes#creating-a-single-code). If the toggle is off, a promotion code is automatically generated for you. Default is ON.
12. In the **Promotion rules** section, create a rule by adding at least one condition and one action. See [Setting up a Promotion](#setting-up-a-promotion) and [Creating Actions](#creating-actions).
13. Click **Create** to save.

## Setting up a Promotion

In the **Promotion rules** section, create conditions for a cart to qualify for the discounts:

1. Select a currency for the promotion in the **Currency** field. If not selected, it will use the store's default currency. If the promotion is applicable for all supported currencies, select **All Currencies**. **Note: Fixed discounts won't factor in exchange rates when applied to multiple currencies.**
2. Choose eligible catalogs for the promotion in the **Catalog** field. If not selected, it will apply to all.
3. Under **Conditions**, select **all** or **any** to apply conditions.
 - **Cart condition**: Configure the promotion by setting either a minimum cart subtotal or quantity of cart items. You can also add conditions to exclude certain items from the cart eligibility. See [Creating a Cart Condition](#creating-a-cart-condition).
 - **Item condition**: Specify the desired product quantity or value. You can also add exclusions that will not contribute to the cart eligibility. See [Creating an Item Condition](#creating-an-item-condition).
 - **Account tag condition**: Target promotions to account shoppers with specific account tags. See [Creating Account Tag Condition](#creating-account-tag-condition).

### Creating a Cart Condition

1. Select **Cart condition** in the **Conditions** section.
2. Set the basic conditions:
 - Choose one of the following condition types:
   - **Subtotal**: Set a minimum or maximum cart subtotal requirement. This determines the total value of items in the cart that must be met for the promotion to apply.
   - **Items quantity**: Set a minimum or maximum number of items in the cart. This counts the total quantity of all items in the cart.
   - **Custom attribute**: This allows you to target carts with specific metadata, such as membership level or customer type. See [Create a Cart with Custom Attributes](/docs/api/carts/create-a-cart#custom-attributes).
 - Select an operator from the following options:
   - **is equal to**
   - **is greater than**
   - **is equal or greater than**
   - **is less than**
   - **is equal or less than**
   - **is between and inclusive of**: The range values are inclusive. For example, `$100–$200` means the cart total must be greater than or equal to `$100` and less than or equal to `$200`.

 - If you selected **Subtotal**, enter the desired amount. This value is used to determine the subtotal of the cart, based on the operator selected in the previous step. For example, if you selected the **is greater than** operator, the  **Subtotal** must exceed the specified amount.
 - If you selected **Items quantity**, enter the required quantity.
 - You can add multiple conditions according to your business requirements.
3. (Optional) Refine condition. Refine condition allows you to **exclude** or **include** items. Click on the **+refine** in the condition editor.
 - To exclude items from the condition, either select **copy exclusions from actions**, or select one of the options under **Add an exclusion** and then make changes as needed. See [Adding Exclusions](#adding-exclusions).
 - To include items for the condition, select one of the options under **sub-total must come from**. See [Adding Inclusions](#adding-inclusions).
4. Click **Done** to apply the conditions.

### Creating an Item Condition

1. Select **Item condition** in the **Conditions** section.
2. Specify the type of cart items:
 - **product**: Click the menu icon next to **No items added**. Click **Select items**. Then, in the **Select Product** window, select a product from the list. For instructions on searching for products in the **Select Product** window, see [Searching for Products](#searching-for-products).
   - **custom sku**: Enter the custom SKU value in the text field instead.
 - **node/hierarchy (category)**: Click the menu icon next to **No items added** and click **Select items**. Then, select the hierarchies or nodes.
 - **attribute**: Select the template from the list, select the attribute, and then set the value for the selected attribute.
 - **custom attribute**: Enter the custom attribute key, select the type, and then set the value for the selected attribute.
 - **group of items**: Select a group of items by clicking the **+refine** to specify the item condition.
3. (Optional) Refine condition. Refine condition allows you to **exclude** or **include** items. Click on the **+refine** in the condition editor.
 - To exclude items from the condition, either select **copy exclusions from actions**, or select one of the options under **Add an exclusion** and then make changes as needed. See [Adding Exclusions](#adding-exclusions).
 - To include items for the condition, select one of the options under **Item must also belong to**. See [Adding Inclusions](#adding-inclusions)
4. Click **Done** to apply the conditions.

:::note
You can exclude or include cart items if you selected **node/hierarchy (category)**, **attribute**, or **custom attribute** while specifying the type of cart items you want to apply to the condition.
:::

#### Creating item custom attribute condition

Item custom attributes can be set in either **Cart condition** or **Item condition**:

**For Cart condition:**
1. Select **Cart condition** in the **Conditions** section.
2. Click **+Refine** in the condition editor.
3. Select **Exclude custom attribute** or **Custom attribute**
4. Enter the name of your attribute key. For example, you can enter *membership level*.
5. Choose one of the following types depending on your attribute key:
 - **String**
 - **Float**
 - **Integer**
 - **Boolean**
6. Select the operator (if applicable):
 - **String** and **Boolean** types do not have operator selection (exact match only)
 - **Float** type, select from the following options:
   - **is less than**
   - **is greater than**
   - **Note**: When using float type in exclusions, only **is equal to** operator is supported.
 - **Integer** type, select from the following options:
   - **is equal to**
   - **is greater than**
   - **is equal or greater than**
   - **is less than**
   - **is equal or less than**
7. Enter the specific value depending on your attribute. For example, *gold* or *silver*.
8. Click **Done** to apply the changes.

**For Item condition:**
1. Select **Item condition** in the **Conditions** section.
2. Select **custom attribute** from the item type dropdown.
3. Enter the name of your attribute key. For example, you can enter *membership level*.
4. Choose one of the following types depending on your attribute key:
 - **String**
 - **Float**
 - **Integer**
 - **Boolean**
5. Select the operator (if applicable):
 - **String** and **Boolean** types do not have operator selection (exact match only)
 - **Float** type, select from the following options:
   - **is less than**
   - **is greater than**
   - **Note**: When using float type in exclusions, only **is equal to** operator is supported.
 - **Integer** type, select from the following options:
   - **is equal to**
   - **is greater than**
   - **is equal or greater than**
   - **is less than**
   - **is equal or less than**
6. Enter the specific value depending on your attribute. For example, *gold* or *silver*.
7. Click **Done** to apply the changes.

### Creating Account Tag Condition

You can create an Account Tag condition and assign one or more tags to it. This enables merchants to target promotions specifically at account shoppers who have those Account Tag(s).

1. Select **Account tag condition** in the **conditions** section.
2. Select one of the followings:
  - **all** means the account shopper must have all of the specified account tags.
  - **any** means the account shopper only needs to have at least one of the tags.
  - **not all** means the account shopper must not have all of the specified account tags.
  - **none** means the account shopper must not have any of the specified account tags.

3. Click **Select tag(s)** to select the desired account tag(s). You can search for the account tag.
4. Click **Done** to apply the changes.

You can remove the account tag(s) by unselecting the tags.

For Account Tags management, see [Account Tags](/docs/commerce-manager/account-management/account-tags).

## Creating Actions

Actions define what happens when the carts meet the conditions. This includes the type of discount applied and how it impacts eligible items.

You can create the following actions:

- **Cart Discount**. See [Creating a Cart Discount Promotion](#creating-a-cart-discount-promotion).
- **Item Discount**. See [Creating an Item Discount Promotion](#creating-an-item-discount-promotion).
- **Buy X, Get Y discount**. See [Creating a BXGY Promotion](#creating-a-bxgy-promotion).
- **Shipping**. See [Creating a shipping promotion](#creating-a-shipping-promotion).

### Creating a Cart Discount Promotion

To create a cart discount promotion, do the following:

1. Select **Cart Discount** in the **Actions** section.
2. Select **percentage** or **amount**.
3. If you selected **percentage**, enter the percentage to be included as the cart total discount.
4. If you selected **amount**, specify the amount for the cart total discount.
5. (Optional) Refine action for exclusions and limitations. Click **+refine**.
 - To exclude items from the discount, Select one of options under **Add an exclusion:**. See [Adding Exclusions](#adding-exclusions).
 - To set discount amount limits (only for percentage discount), select **Maximum allowed discount**. Enter the maximum allowed discount in the **value** field.
6. Click **Done** to apply the changes.

### Creating an Item Discount Promotion

To create an item discount promotion, do the following:

1. Select **Item discount** in the **Actions** section.
2. Choose **percentage**, **amount**, or **fixed price**.
3. Enter the value in the **value** field based on your selection in the previous step.
4. If you selected **fixed price**, enter the number of quantities in the **quantity** field.
5. Choose how the discount applies to items. Select **all**, **cheapest**, or **most expensive** items in cart. The default value is **all**.
6. If you selected the **cheapest** or **most expensive** options, select quantities for the items to be included in the cart.
7. (Optional) Refine action for exclusions and limitations. Click **+refine**.
 - To exclude items from the discount, Select one of options under **Add an exclusion:**. See [Adding Exclusions](#adding-exclusions).
 - To set discount amount limits (only for percentage discount), select **Maximum discount amount**. Enter the maximum allowed discount in the **value** field.
 - To set the max quantity of the same SKUs can get discount, select **Maximum quantity for each line item**. Enter the maximum allowed quantity value.
 - To set the max discounted quantities across all eligible items, select **Maximum discounted quantities across all eligible items**. Enter the maximum allowed quantity value.
8. Click **Done** to apply the changes.

### Creating a BXGY Promotion

To create a **Buy X, Get Y discount** promotion, do the following:

1. Select the required conditions. See [Setting up a Rule Promotion](#setting-up-a-promotion).
2. Select **Buy X, Get Y discount** in the **Actions** section.
3. Select either **percentage** or **amount** or **fixed price** discount.
4. If you selected **percentage**, enter the percentage value.
5. If you selected **amount**, specify the amount for the promotion.
6. If you selected **fixed price**, specify the amount and quantity.
7. Select **all**, **cheapest**, or **most expensive** items in the cart to qualify for the promotion.
8. Specify the type of items to include in the promotion from the following options:
  - **product**: Click the menu icon next to **No items added**. Click **Select items**. Then, in the **Select Product** window, select a product from the list. For instructions on searching for products in the **Select Product** window, see [Searching for Products](#searching-for-products).
    - **custom sku**: Enter the custom SKU value in the text field instead.
  - **from node/hierarchy (category)**: Click the menu icon next to **No items added** and click **Select items**. Then, select the hierarchies or nodes.
  - **from attribute**: To add the attribute, do the following:
    1. Select the template from the list.
    2. Select the attribute from the list.
    3. Select the value from the list corresponding to the chosen attributes.
  - **custom attribute**: Enter the custom attribute key, select the type, and then set the value for the selected attribute.
  - **group of items**: Select a group of items by clicking the **+refine** to select items.
9. (Optional) Refine action for exclusions and limitations. Click **+refine**.
 - To exclude items from the discount, Select one of options under **Add an exclusion:**. See [Adding Exclusions](#adding-exclusions).
 - To include items for the discount (for **node/hierarchy (category)** or **Attribute**), select one of the options under **Item must also belong to**. See [Adding Inclusions](#adding-inclusions)
 - To set discount amount limits (only for percentage discount), select **Maximum discount amount**. Enter the maximum allowed discount in the **value** field.
 - To set the max quantity of the same SKUs can get discount, select **Maximum quantity for each line item**. Enter the maximum allowed quantity value.
 - To set the max discounted quantities across all eligible items, select **Maximum discounted quantities across all eligible items**. Enter the maximum allowed quantity value.
10. Click **Done** to apply the changes.

:::note
You can exclude items from promotion only if you selected **node/hierarchy (category)** or **attribute** or **custom attribute** while specifying the type of cart items.
:::

### Creating a Shipping Promotion
To create a **Shipping discount** promotion, do the following:

1. Select **Shipping** in the **Actions** section.
2. Select **a percentage**, **an amount** or **a fixed price**.
3. Enter the value in the **value** field based on your selection in the previous step.
4. (Optional) If there is targeted shipping type for discount, then click **+refine**.
5. Select **Add shipping method or service**
6. Check the checkbox for **Apply discount to**. Enter the shipping type value that matches targeted cart shipping group `shipping_type` value and hit Enter. For example, "fedex", "UPS".
 - You can add more than one shipping type values.
7. Click **Done** to apply the changes.

### Creating a Bundle Promotion
To create a bundle promotion, do the following:

1. Select **Item condition** in the **Conditions** section.
  - Refer to [Create Item Condition](#creating-an-item-condition).
2. Select **group of items**, then click **+ Refine**.
3. Select one of the following options to target items:
  - **Add product**: Enter the values directly (including custom sku value) or click the menu and then **Select items**. In the **Select Product** window, choose a product from the list. For instructions on searching for products in the **Select Product** window, see [Searching for Products](#searching-for-products).
    - (Optional): **+refine** to set the minimum quantity required.
 -  **Add node/hierarchy (category)**: Click the menu and then **Select items**, then select the checkboxes for the desired nodes/hierarchies(categories).
    - (Optional): **+refine** to set minimum quantity, inclusions and exclusions.
 -  **Add attribute**: Select the template from the list, choose the attribute, and then set the value for the selected attribute.
    - (Optional): **+refine** to set minimum quantity, inclusions and exclusions.
4. (Optional) Click **+refine** at the **group of items** level to add more groups of items.
5. Select actions for how to apply the discount. See [Creating actions](#creating-actions).
  - NOTE: If you want to give a **bundle discount** to a specific group of items, select **Buy X, Get Y discount**.
    1. Choose the type of discount **percentage** or **amount** or **fixed price**. Then enter discount the value.
    2. Choose **group of items** from **product** dropdown.
    3. Click **+refine** to add items to the group. Discount will apply to the items in the group.
6. Click **Done** to apply the changes.

## Adding Exclusions

Exclusions allow you to exclude specific items from the promotion, ensuring they are not eligible for the discount. To exclude certain items from a promotion, follow these steps:

1. Click **+refine**.
2. Choose one of the following exclusion types under **Add an exclusion**:
 -  **Exclude product**: Enter the values directly (including custom sku value) or click the menu and then **Select items**. In the **Select Product** window, choose a product from the list. For instructions on searching for products in the **Select Product** window, see [Searching for Products](#searching-for-products).
 -  **Exclude node/hierarchy (category)**: Click the menu and then **Select items**, then select the checkboxes for the desired nodes/hierarchies(categories).
 -  **Exclude attribute**: Select the template from the list, choose the attribute, and then set the value for the selected attribute.
 -  **Exclude custom attribute**: Enter the custom attribute key, select the type, and then set the value for the selected attribute. **Note**: For float type custom attributes, only the **is equal to** operator is supported in exclusions.
 -  **Copy exclusions from conditions** or **Copy exclusions from actions**.
3. Click **Done** to apply the exclusions.

## Adding Inclusions

Inclusions allow you to include specific items from the parent conditions or actions to narrow down the target items. Inclusions are available in **Cart condition**, **Item condition** and the **Buy X Get Y discount** action.

To include items for a **Cart condition**, follow these steps:

1. Under the **Cart condition**, click **+refine**.
2. Choose one of the following inclusion types under **Sub-total must come from:**
  -  **Node/Hierarchy (Category)**: Click the menu and then **Select items**, then select the checkboxes for the desired nodes/hierarchies(categories).
  -  **Attribute**: Select the template from the list, choose the attribute, and then set the value for the selected attribute.
  -  **Custom attribute**: Enter the custom attribute key, select the type, and then set the value for the selected attribute.
3. Fill the required fields.
4. Click **Done** to apply the inclusions.

To include items for an **Item condition**, follow these steps:
1. Under the **Item condition** , choose one of the following options:
  -  **Node/Hierarchy (Category)**: Click the menu and then **Select items**, then select the checkboxes for the desired nodes/hierarchies(categories).
  -  **Attribute**: Select the template from the list, choose the attribute, and then set the value for the selected attribute.
2. Click **+refine**.
3. Choose one of the following inclusion types under **Item must also belong to**:
  -  **Node/Hierarchy (Category)**
  -  **Attribute**
  -  **Custom attribute**
4. Fill the required fields.
5. Click **Done** to apply the inclusions.

To include items for a **Buy X, Get Y discount** action, follow these steps:
1. Select **Buy X, Get Y discount** action.
2. Choose one of the following item options as higher level target:
  -  **from node/hierarchy (category)**
  -  **from attribute**
  -  **custom attribute**
3. Choose one of the following inclusion types under **Item must also belong to**
  -  **Node/Hierarchy (Category)**
  -  **Attribute**
  -  **Custom attribute**
4. Fill the required fields.
5. Click **Done** to apply the inclusions.

## Auto Add Free Item and Product Suggestions

You can configure the auto-add feature for free items when using **Buy X, Get Y discount** for a gift-with-purchase promotion. For example, if a customer buys a pair of shoes, a pair of socks will be automatically added to the cart as a free gift when the eligible shoes are added to the cart.
The auto-add feature will only occur when the target item is 100% discounted (i.e., free). If the target item is not completely discounted, you can enable the **Add Upsell Suggestion** option. This will display a promotional suggestion to the shopper, informing them about the discounted item.

### Auto-Add and Product Suggestions Behavior Based on Settings
- It is recommended to have **Coupon-driven** toggle OFF for both Auto-Add and Product Suggestions.
- If the **Coupon-driven** toggle is set to ON, discount codes must be re-applied to carts after adding eligible items in order for discount values to apply.  The bulk-add items endpoint allows users to both add items and re-apply discount codes in single requests.  For more details, see [Bulk Add To Cart](/docs/carts-orders/bulk-add-to-cart).

| **Auto Add** | **Show Suggestions** | **Item Discount** | **Result** |
|--------------|-----------------------|-------------------|------------|
| true         | true                  | 100%              | Free item auto added. No suggestions because the free item is already added. |
| false        | true                  | 100%              | Free item not auto added. Suggestions show in the cart. |
| false        | false                 | 100%              | Free item not added. No suggestions. |
| null         | null                  | 100%              | Free item not added. No suggestions. |
| true         | false                 | 100%              | Free item auto added. No suggestions. |
| true         | true                  | Less than 100%    | Unable to set such promotion because auto-add requires 100% discount. |
| false        | true                  | Less than 100%    | No item auto added. Suggestions show in the cart. |
| false        | false                 | Less than 100%    | No item auto added. No suggestions. |

1. Select **Buy X, Get Y discount** action.
2. Enter the discount percentage value.
3. Choose **product** from the item type dropdown.
4. Select or enter the item value.
5. Click **+refine**.
6. (Optional) Select **Auto-add the product** and **Add upsell suggestion**.
7. Click **Done**.

## Searching for Products

To find specific products to include in your promotion, use the **Select Product** window:

### Quick Search
1. Use the search bar at the top to quickly search by **SKU** (default).
2. Select the first dropdown to change the search field (e.g., **SKU**, **Name**, **Slug**, etc.).
3. Select the second dropdown to change the search operator:
   - **is**
4. Enter your search term in the text field.
5. Click **Search**.

### Advanced Filtering
To apply multiple filters:
1. Click **+ Add Filter** in the left sidebar.
2. Select from the available filter options:
   - **ID**
   - **Name**
   - **SKU**
   - **Slug**
   - **MPN**
   - **UPC/EAN**
   - **Product Type**
   - **Context Tags**
3. Configure each filter as needed.
4. Click **Clear all** to remove all applied filters.

## Duplicating a Promotion

You can duplicate an existing promotion and reuse its details as required in a new promotion. The date and priority fields are not included in the duplication.

1. Go to **STORE > Promotions Builder**.
2. To duplicate a promotion, follow one of these steps on the **All Promotions** page:
 - Click the ellipsis at the end of the promotion row, then select **Duplicate**.
 - Open the promotion you want to duplicate, and click the ellipsis next to the Save button, then select **Duplicate**.

The duplicated promotion opens. Make the necessary updates, then click **Save** to save the new promotion.

## Editing Custom Fields in a Promotion
In order to use custom fields in Promotions Builder, you need to create flows in the store. See [Creating FLows](/docs/commerce-manager/flows) for how to create flows. The **slug** value for promotions builder is **rule-promotions**.
Once you have created the flows and field, then you can edit the custom fields in the Promotions Builder.

1. In the Promotions Builder editing page, locate the **Custom Fields** at the bottom of page.
2. Expand the section.
3. Edit the fields.
4. Click **Save** to save the changes.

## Searching for Promotions

You can search for promotions from the promotions list page using filters.

1. On the **Promotions Builder** list page, click **Add Filter** or select the dropdown **Promotion Name** on the right.
2. Use the available filters to search for the targeted promotions.
3. You can narrow down your search by applying multiple filters such as **Promotion Name**, **Coupon Code**, **Status**, **Enabled**, **Stackable**, and **Override Stacking**.

## Related Resources

- [Rule Promotions API](/docs/api/promotions-builder/rule-promotions-api)

---

## Creating Promotion Codes

### Creating a Single Code

1. In Commerce Manager, go to **Merchandise > Promotions > Builder**.
1. Select the promotion for which you want to create a code or create a new promotion.
1. Go to the **Promotion Codes** tab.
1. (Optional) On the right-hand side, select **Add a new promotion code**.

    The **Add a new promotion code** button is disabled for automatic promotions. To manually create a code, ensure the **Coupon-driven** checkbox is selected while [creating the promotion](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder).
1. In the **Create Single code** tab:
    1. Provide a code in the **Create a code** field.
    1. Choose your audience:
        - **Public**: The code is available to everyone.
        - **Private**: The code is specific to a particular shopper, so you’ll need to enter their unique identifier.
    1. Set the code type:
        - **Regular code**: A standard code that can be used by any shopper.
        - **First time Shopper code**: A code for shoppers using it for the first time. This option is only available when you set the audience to **Public**.
    1. Define limitations. Choose either **No limitations** or **Add limitations**. This option is only available when you set the code type to **Regular code**.

        If you select **Add limitations**, set at least one of the following limitations:
        - specify the **Max code use across all checkouts** to control how many times the code can be used overall. Each time a shopper checkouts, the usage is tracked against this number.
        - specify the **Max times a shopper can apply the code** to control how many times the code can be used per shopper. See [Create Max Uses Per Shopper Promotion Codes](/docs/promotions-builder/promotions-builder-codes/create-max-use-limit-promotion-codes)
          - specify the max use limitation to **Include Guests** or **Exclude Guests**.
            - See the API spec on how to use [max_uses_per_shopper.includes_guests](/docs/promotions-builder/promotions-builder-codes/create-max-use-limit-promotion-codes#body)

        By default, the Commerce Manager uses the per checkout method. However, if you need to limit usage on a `per_application` basis, you can configure this via the backend. See [Creating Promotion codes](/docs/promotions-builder/promotions-builder-codes/create-promotion-codes).
1. Select **Save Changes**.

## Searching for a Promotion Code

You can search for a promotion code across all promotions.

1. In Commerce Manager, go to **Merchandise > Promotions > Builder**.
1. In the **Search** field, enter the promotion code you are looking for on the **All Promotions** page.

    The promotion name associated with the promotion code is displayed.

## Bulk generate promotion codes

:::caution
- You can only generate a maximum of 1000 codes for a single promotion.
- When generating more than 1000 codes, the promotion's duration must be limited to a maximum of 365 days from its start date. If you need to increase the number of promotion codes for a single promotion, reach out to our [customer success team](mailto:customersuccess@elasticpath.com).
:::

With bulk generating codes, you can generate large number of unique promotion codes. To do so, follow these steps:

1. In Commerce Manager, go to **Merchandise > Promotions > Builder**.
2. Select the promotion name for which you want to create codes or create a new promotion.
3. Go to the **Promotion Codes** tab.
4. On the right-hand side, click **Add a new promotion code**.
5. In the **Bulk generate codes** tab, enter the following details:

 - **Number of codes to generate** : Specify the number of codes to be generated.
 - **Code character limit** : Specify the desired code length, which ranges from 8 to 16 characters. The default code length is eight characters, and a dash is added after every four characters in the code. For example, *aa2b-3c4d*.
 - (Optional) **Assign a prepend value to all codes** : Add a prefix value to the generated codes. When codes are generated, the specified prepend value is added as a prefix to each code. For example, if you set *summer* as prepend value and *aa2b-3c4d* is generated, the promotion code is *summer-aa2b-3c4d*.
 - (Optional) **Assign a maximum time each code can be applied** : Enter the maximum number of usages of a code for a promotion. If no value is set, customers can use the code unlimited number of times. We recommend you to set value greater than or equal to 1.

6. Click **Bulk-generate code**.

  The page will display a loading indicator while the codes are being generated. Once the job is complete, the generated codes will appear on the Promotion Codes page.

## Export promotion codes

Using the **Manage Code Export** tab, you can export your promotion codes and download them in CSV format. To do so, follow these steps:

1. In Commerce Manager, go to **Merchandise > Promotions > Builder**.
1. Select the promotion name for which you want to export the codes.
1. Go to the **Promotion Codes** tab.
1. On the right side, click **Manage Code Export**.
1. Click **Create export** to initiate the code export process.

The page will display a loading indicator while the codes are being exported. Once the export is completed, you can download the exported file in CSV format.

## Demos

import CardDisplay from "/src/components/CardDisplay";

<grid class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 gap-6">
  <CardDisplay
    mediaSrc="https://share.vidyard.com/watch/6Wc7L4CLDTnnnA14BF2x4V?"
    mediaType="embed"
    title=""
    description="Generating Bulk Coupon Codes in Commerce Manager"

  />
  <CardDisplay
    mediaSrc="https://share.vidyard.com/watch/qiyw6J32KJSV27xGKehUDT?"
    mediaType="embed"
    title=""
    description="Maximum Promotions Usage Limitations for Guest Shopper"

  />
</grid>

---

## Overview(Promotions-builder)

The Promotions Builder provides the flexibility to offer diverse discounts to shoppers. Leveraging a rule-based implementation behind the scenes, this feature allows users to set specific promotion eligibility conditions and define corresponding discount actions at various levels.

## Strategic Promotion Planning
Before diving into the configuration, it's important to understand how different promotional strategies can address specific business objectives. The following sections outline key promotional approaches that merchandisers can implement using the Promotions Builder to solve various business challenges and drive revenue growth.

### Promotions for Customer Acquisition
If the goal is to expand the customer base, acquisition-focused promotions are key.

#### First-Time Purchase Discounts
Offer a discount for the first purchase to incentivize new customers to try the product or service. Use cart conditions to identify new customers and apply percentage or fixed discounts to encourage initial purchases.

#### Referral Programs
Implement a referral program to leverage existing customers to bring in new ones. Configure custom attributes to track referral codes and reward both the referrer and new customer with discounts.

#### Free Trials or Samples
Provide free trials or samples to allow potential customers to experience the value firsthand. Use item discounts with fixed pricing to offer products at no cost for qualifying customers.

### Promotions for Increasing Average Order Value
To boost revenue per transaction, promotions should encourage customers to spend more

#### Bundling Offers
Combine related products into bundles and offer them at a discounted price. Use cart items conditions to identify specific product combinations and apply item discounts to the bundle.

#### Spend More, Save More
Create tiered discounts based on purchase amount. For example, "Spend $100, get 10% off; Spend $200, get 20% off." Configure cart conditions with minimum subtotal requirements and corresponding percentage discounts.

#### Upselling or Cross-selling Incentives
Offer discounts on upgrades or complementary items when a customer makes a purchase. Use cart items conditions to detect primary purchases and apply item discounts to related products.

### Promotions for Enhancing Customer Loyalty
Retaining customers is crucial for long-term success. Promotions can help build loyalty.

#### Loyalty Programs
Implement a loyalty program with points or rewards for repeat purchases. Use custom attributes to track customer loyalty status and provide exclusive discounts for loyal customers.

#### Exclusive Deals for Existing Customers
Offer exclusive discounts or early access to sales for loyal customers. Configure promotions with custom attributes that identify returning customers and provide them with special pricing.

#### Personalized Offers
Use customer data to create personalized promotions tailored to individual preferences. Leverage custom attributes and cart items conditions to create targeted promotions based on purchase history and customer segments.

### Promotions for Moving Excess Inventory
When there's excess stock, promotions can help clear it out.

#### Flash Sales
Run short-term, deep-discount sales to create urgency and drive quick purchases. Use time-limited promotions with significant percentage discounts on specific product categories or SKUs.

#### Clearance Sales
Offer significant discounts on discontinued or end-of-season items. Configure item discounts with percentage or fixed amount reductions on specific product categories or SKUs.

#### Buy-One-Get-One (BOGO) Deals
Use BOGO offers to move large quantities of stock. Implement BXGY promotions where customers receive additional items at no cost or reduced price when purchasing qualifying products.

## Configuration options
Within the Promotions Builder, you can configure promotions using various conditions:

  - **[Cart condition](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#creating-a-cart-condition)**: Define a minimum cart subtotal or quantity requirements.
  - **[Item condition](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#creating-an-item-condition)**: Specify product SKUs, product categories, products with attributes, or custom attributes for eligibility.
  - **[Account Tags condition](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#creating-account-tag-condition)**: Specify account tag(s) for the shopper condition.

Promotions in the Promotions Builder support the following actions:

**[Cart Discount](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#creating-a-cart-discount-promotion)**: A cart discount applies to all items in the cart unless specific exclusions are specified. It can be either a fixed discount or a percentage discount.

  - Fixed discount: This reduces the cart total by a fixed amount, such as $5.00 off.
  - Percentage discount: This reduces the cart total by a specific percentage, such as 10% off.

**[Item Discount](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#creating-an-item-discount-promotion)**: An item discount applies to the eligible items specified in the conditions. It can be a fixed amount, percentage, fixed price, or other discount specified such as BXGY.

**[BXGY](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#creating-a-bxgy-promotion)**: Buy X and Get Y (BXGY) discounts apply to the items identified within the promotional actions. This means that when a Buy X Get Y promotion is triggered, the specified items receive the associated discounts outlined in the promotion's configuration.

**[Shipping Discount](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#creating-a-shipping-promotion)**: Shipping discount applies to eligible shipping groups. The discount applies to the shipping base price, excluding tax and fees.

Exclusions can be applied to any of these conditions and promotions, allowing you to refine your discount strategies further. For example, you can exclude specific products, categories, or attributes from promotions, providing more flexibility in setting up promotion rules.

To understand the difference between Promotions Standard and Promotions Builder, see [Feature Comparison](/docs/promotions-builder/builder-vs-standard).

As a best practice, we recommend creating new promotions in the Promotions Builder and allowing Promotions Standard to expire. While Promotions Standard can currently run side by side with new ones, transitioning to the Promotions Builder ensures alignment with updated features and facilitates smoother management of promotions over time.

## Stacking and Prioritizing Multiple Promotions
You can create a priority number for both stackable and non-stackable promotions. Simultaneously apply multiple promotions by stacking both cart-level and item-level discounts on top of each other. The priority number assigned to each stackable promotion determines the order in which they are applied. Higher numbers indicate higher priority, meaning those promotions will be applied first.

For example, if you have two promotions that can be stacked, the promotion with priority 90 will be applied before the promotion with priority 60.

If no priority is set, the promotions are applied sequentially based on their creation dates. The newest promotion is applied first and discounted prices calculated against any previously-discounted item prices. For example, if a SKU matches the criteria of the multiple promotions, the promotions will be applied in order from the newest to the oldest. If the original item price is $50 and the newest promotion applies a 10% discount, the item price would be reduced to $45. The next promotion would then be applied to this new price.

Standard Promotions are always applied first, regardless of any priorities set. Once all Standard Promotions have been applied, promotions configured in Promotions Builder are applied in the order determined by their assigned priority numbers.

### Override Stacking
Override stacking enables a promotion to be stacked on otherwise non-stackable promotions. This enables you to create promotions that will always stack, even if the first applied promotion is non-stackable. An example use case is offering free shipping on all orders during a sale. You can set up a free shipping promotion with **Override stacking** turned ON. This ensures that the free shipping promotion will always apply, regardless of other promotion types, without needing to modify existing promotions. The order in which promotions stack depends on their Priority. The promotion with the highest Priority value takes precedence.

## How To Guides
To configure specific promotion types using the Promotions Builder, see these [How-To Guides](/guides/How-To/promotions-builder/index).

## Demos

<iframe class="vidyard_iframe"
  mediaType="embed"
  title="Promotions Builder" src="//play.vidyard.com/7CCnVZgAgJ2h47oNRwj5kK.html?" width="640" height="360" scrolling="no" frameborder="0" allowtransparency="true" allowfullscreen referrerpolicy="no-referrer-when-downgrade"></iframe>

---

## Creating Cart-level Fixed Discount Promotions

:::caution
- We recommend not to set maximum discount value for this promotion. Setting maximum discount value for this promotion conflicts with the cart fixed discount value. For example, if the maximum discount value is $10 and the cart fixed discount value is $20, the cart gets $10 discount only.
- The **Promotion Exclusions** setting specifies the products to be excluded from the cart-level promotions, such as `fixed_discount` and `percent_discount`. However, the stores that use [simple calculation method](/docs/api/settings/settings-introduction#calculation-method) do not support excluding products from promotions.
- We recommend to use **Advanced (Conditions v2)** settings.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. In the **Name** field, enter a name for the promotion.
1. In the **Description** field, enter a description for the promotion.
1. In the **Date range** field, select the start date and time and the end date and time of the promotion.
1. To enable the promotion, click the **Enabled** toggle.
1. (Optional) To automatically apply the promotion, click the **Automatic** toggle.

    If this field is not selected, the promotion requires the buyer to enter a code in the cart to get the discount. For more information, see the [Adding codes](/docs/commerce-manager/promotions-standard/overview#creating-promotion-codes) section.
1. (Optional) In the **Minimum cart value** section, click **Add minimum cart value**.
   The **Set minimum cart value** window is displayed.
   1. In the **Amount** field, enter a minimum cart value before the promotion can be applied.
   1. In the **Select currency** field, select a currency.
      You can add one or several value specifications in different currencies. For more information about currencies, see [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).
    1. Click **Save**.
1. In the **Promotion type** field, select **Cart fixed discount**.
1. In the **Define schema** section, do the following:
    1. In the **Currencies** subsection:
        1. Click **Add currency**.

            The **Add currency** window is displayed.
        1. In the **Amount** field, specify amount for the promotion.
        1. In the **Select currency** field, select a currency from the list. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
        1. Click **Save**.
    1. In the **Catalogs** field, select the catalogs to be applied for this promotion from the list.

        If you do not select any catalogs from the list, all catalogs will be applied for the promotion.
    1. In the **Promotion Exclusions** subsection, do the following:
        1. Go to **Products**.
        1. Click **Add exclude**.
        1. In the **Condition Type** field, choose **SKUs or Product IDs** to be excluded from a promotion.
        1. In the **SKUs/Product IDs** field, enter the IDs or SKUs of the products that you want to exclude from a cart-level promotion.
        1. Click **Add Condition**.
        1. In the **Simplified (Conditions v1)** settings, do the following:
            1. Click **Add exclude**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a cart-level promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.

            You can repeat the above steps to add multiple conditions.
        1. To exclude attributes and hierarchies or nodes from a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be excluded from a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes, and hierarchies or nodes to be excluded from a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
1. Click **Save**.

## Related Resources

- [Promotion Management Overview](/docs/commerce-manager/promotions-standard/overview)
- [Customers](/docs/customer-management/customers)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

---

## Creating Cart-level Percentage Discount Promotions

:::caution
- The **Promotion Exclusions** setting specifies the products to be excluded from the cart-level promotions, such as `fixed_discount` and `percent_discount`. However, the stores that use [simple calculation method](/docs/api/settings/settings-introduction#calculation-method) do not support excluding products from promotions.
- We recommend to use **Advanced (Conditions v2)** settings.

:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. In the **Name** field, enter a name for the promotion.
1. In the **Description** field, enter a description for the promotion.
1. In the **Date range** field, select the start date and time and the end date and time of the promotion.
1. In the **Promotion type** field, select **Cart percent discount**.
1. To enable the promotion, click the **Enabled** toggle.
1. (Optional) To automatically apply the promotion, click the **Automatic** toggle.

    If this field is not selected, the promotion requires the buyer to enter a code in the cart to get the discount. For more information, see the [Adding codes](/docs/commerce-manager/promotions-standard/overview#creating-promotion-codes) section.
1. (Optional) In the **Minimum cart value** section, click **Add minimum cart value**.
   The **Set minimum cart value** window is displayed.
   1. In the **Amount** field, enter a minimum cart value before the promotion can be applied.
   1. In the **Select currency** field, select a currency.
      You can add one or several value specifications in different currencies. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
    1. Click **Save**.
1. (Optional) In the **Maximum discount value** field, enter the maximum possible discount amount and currency.
1. In the **Define schema** section, do the following:
    1. Click **Add percentage**.

        The **Add currency** window is displayed.
    1. In the **Percentage** field, enter percentage to be included for the promotion.

        You can add up to six decimal places for the percentage to be applied for the promotion.
    1. In the **Select currency** field, select a currency from the list. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
    1. Click **Save**.
    1. In the **Catalogs** field, select the catalogs to be applied for this promotion from the list.

        If you do not select any catalogs from the list, all catalogs will be applied for the promotion.
    1. In the **Promotion Exclusions** subsection, do the following:
        1. Go to **Products**.
        1. Click **Add exclude**.
        1. In the **Condition Type** field, choose **SKUs or Product IDs** to be excluded from a promotion.
        1. In the **SKUs/Product IDs** field, enter the IDs or SKUs of the products that you want to exclude from a cart-level promotion.
        1. Click **Add Condition**.
        1. In the **Simplified (Conditions v1)** settings, do the following:
            1. Click **Add exclude**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a cart-level promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.

            You can repeat the above steps to add multiple conditions.
        1. To exclude attributes and hierarchies or nodes from a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be excluded from a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes, and hierarchies or nodes to be excluded from a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
1. Click **Save**.

## Related Resources

- [Promotion Management Overview](/docs/commerce-manager/promotions-standard/overview)
- [Customers](/docs/customer-management/customers)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

---

## Creating Bundle Discount Promotions

:::caution
- We recommend not to set maximum discount value for this promotions. Setting maximum discount value for this promotion conflicts with the promotion settings.
- Hierarchy-based promotions are not supported for fixed bundle discount promotion.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. In the **Name** field, enter a name for the promotion.
1. In the **Description** field, enter a description for the promotion.
1. In the **Date range**  field, select the start date and time and end date and time of the promotion.
1. To enable the promotion, click the **Enabled** toggle.
1. (Optional) To automatically apply the promotion, click the **Automatic** toggle.
  If this field is not selected, the promotion requires the buyer to enter a code in the cart to get the discount. For more information, see the [Adding codes](/docs/commerce-manager/promotions-standard/overview#creating-promotion-codes) section.
1. (Optional) In the **Minimum cart value** field, click **Specify values**.
   The **Set minimum cart value** window is displayed.
      1. In the **Amount** field, enter a minimum cart value before the promotion can be applied
      1. In the **Select currency** field, select a currency.
      You can add one or several value specifications in different currencies. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
      1. Click **Save**.
1. In the **Promotion type** field, select **Bundle**.
1. (Optional) In the **Quantity limit per use** field, specify the maximum number of application of a promotion per cart for a single use of a promotion.

    Each unique product in the cart will qualify for a promotion for X number of times depending upon what you specified in the **Quantity limit per use** field. For example, if the **Quantity limit per use** field is set to 1, and *SKU A* and *SKU B* are in the cart with a quantity of two each, only one instance of each *SKU A* and *SKU B* will qualify for a promotion.
1. In the **Define schema** section, do the following:
    1. Under **Currencies**, click **Add currency**.
    1. In the **Amount** field, add the amount for the bundle.
    1. In the **Select currency** field, select a currency code.
    1. Click **Save**.
    1. Under **Bundle requirements**, click **Add requirement**.
    1. In the  **Product SKUs / Product IDs** field, enter the product IDs or SKUs of the first item in the bundle.
    1. In the **Quantity** field, enter the quantities of products to be applied for the promotion.
    1. Click **Save**.
    1. Repeat step 5 to add more items to the bundle.
    1. Click **Save**.
1. Click **Save**.

## Example for Bundle

For a bundle promotion *(SKU1 or SKU2 ) + SKU3 for $20*, the promotion is applied if the bundle contains *SKU1 and SKU3* or *SKU2 and SKU3*. Do the following to define schema for this promotion.

1. Click **Add requirement** and enter *SKU1* and *SKU2* separated by a comma.
1. Click **Save**.
1. Click **Add requirement** again and enter *SKU3*.
1. Click **Save**.

## Related Resources

- [Promotion Management Overview](/docs/commerce-manager/promotions-standard/overview)
- [Customers](/docs/customer-management/customers)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

---

## Creating Free Gift Promotions

:::caution
- We recommend not to set maximum discount value for this promotions. This setting doesn’t have any effect on the promotion.
- Hierarchy-based promotions are not supported for fixed bundle discount promotion and free gift promotion.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. In the **Name** field, enter a name for the promotion.
1. In the **Description** field, enter a description for the promotion.
1. In the **Date range**  field, select the start date and time and end date and time of the promotion.
1. To enable the promotion, turn on the **Enabled** toggle.
1. (Optional) To automatically apply the promotion, enable the **Automatic** toggle.

    If this field is not selected, the promotion requires the buyer to enter a code in the cart to get the discount. For more information, see the [Adding codes](/docs/commerce-manager/promotions-standard/overview#creating-promotion-codes) section.
1. (Optional) In the **Minimum cart value** field, click **Specify values**.

    The **Set minimum cart value** window is displayed.
   1. In the **Amount** field, enter a minimum cart value before the promotion can be applied.
   1. In the **Select currency** field, select a currency.
      You can add one or several value specifications in different currencies. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
    1. Click **Save**.
1. In the **Promotion type** field, select **Free gift**.
1. (Optional) In the **Quantity limit per use** field, specify the maximum number of application of a promotion per cart for a single use of a promotion.

    Each unique product in the cart will qualify for a promotion for X number of times depending upon what you specified in the **Quantity limit per use** field. For example, if the **Quantity limit per use** field is set to 1, and *SKU A* and *SKU B* are in the cart with a quantity of two each, only one instance of each *SKU A* and *SKU B* will qualify for a promotion.
1. In the **Define schema** section, do the following:
    1. Under **Bundle requirements**, click **Add requirement**.

        The **Add requirement** window is displayed.
    1. In the **Product SKUs / Product IDs** field, enter the product IDs or SKUs for which a free gift is included.
    1. In the **Quantity** field, enter the quantities of products to be applied for the promotion.
    1. Click **Save**.
    1. (Optional) Enable the **Automatically add free gift items to the cart** toggle to add free gifts automatically to the shopping cart.

        :::caution
        The **Automatically add free gift items to the cart** toggle is enabled only when the **Automatic** toggle is turned on. If there is insufficient stock for all eligible free products, no free gifts are added to the cart.
        :::

    1. Under **Gifts**, Click **Add gift**.

        The **Add requirement** window is displayed.
    1. In the **Product SKUs / Product IDs** field, enter the product IDs or SKUs of the free gift items separated by comma.
    1. Click **Save**.
1. Click **Save**.

## Related Resources

- [Create a Free Gift Promotion](/docs/commerce-manager/promotions-standard/item-level-promotions/free-gift-promotions)
- [Promotion Management Overview](/docs/commerce-manager/promotions-standard/overview)
- [Customers](/docs/customer-management/customers)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

---

## Creating Item Fixed Discount Promotions

:::caution
- We recommend not to set maximum discount value for this promotions. Setting maximum discount value for this promotion conflicts with the promotion settings.
- We recommend to use **Advanced (Conditions v2)** settings.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. In the **Name** field, enter a name for the promotion.
1. In the **Description** field, enter a description for the promotion.
1. In the **Date range**  field, click the start date and time and end date and time of the promotion.
1. To enable the promotion, click the **Enabled** toggle.
1. (Optional) To automatically apply the promotion, click the **Automatic** toggle.

    If this field is not selected, the promotion requires the buyer to enter a code in the cart to get the discount. For more information, see the [Adding codes](/docs/commerce-manager/promotions-standard/overview#creating-promotion-codes) section.
1. (Optional) In the **Minimum cart value** field, click **Specify values**.
   The **Set minimum cart value** window is displayed.
   1. In the **Amount** field, enter a minimum cart value before the promotion can be applied.
   1. In the **Select currency** field, select a currency.
      You can add one or several value specifications in different currencies. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
    1. Click **Save**.
1. In the **Promotion type** field, select **Item fixed discount**.
1. (Optional) In the **Quantity limit per use** field, specify the maximum number of application of a promotion per cart for a single use of a promotion.

    Each unique product in the cart will qualify for a promotion for X number of times depending upon what you specified in the **Quantity limit per use** field. For example, if the **Quantity limit per use** field is set to 1, and *SKU A* and *SKU B* are in the cart with a quantity of two each, only one instance of each *SKU A* and *SKU B* will qualify for a promotion.
1. In the **Define schema** section, do the following:
    1. In the **Currencies** subsection:
        1. Click **Add currency**.
        1. In the **Amount** field, add the amount.
        1. In the **Select currency** field, select a currency.
        1. Click **Save**.
    1. In the **Catalogs** field, select the catalogs to be applied for this promotion from the list.

        If you do not select any catalogs from the list, all catalogs will be applied for the promotion.
    1. In the **Promotion Conditions** subsection:

        1. To include products in a promotion, do the following:
            1. Go to **Products**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **SKUs or Product IDs** to be included in a promotion.
            1. Click **Add Condition**.
        1. To include attributes and hierarchies or nodes in a promotion, do the following:
            1. Go to **Simplified (Conditions v1)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be included in a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to include in a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
        1. To include attributes and hierarchies or nodes in a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be included in a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to include in a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be included in a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes, and hierarchies or nodes to be included in a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
    1. In the **Promotion Exclusions** subsection:
            :::caution
             **Promotion Exclusions** subsection is enabled only when you update the **Simplified (Conditions v1)** or **Advanced (Conditions v2)** settings in the **Promotion Conditions** subsection.
            :::
        1. To exclude products from a promotion, do the following:
            1. Go to **Products**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **SKUs or Product IDs** to be excluded from a promotion.
            1. Click **Add Condition**.
        1. To exclude attributes and hierarchies or nodes from a promotion, do the following:
            1. Go to **Simplified (Conditions v1)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
        1. To exclude attributes and hierarchies or nodes from a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be excluded from a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes, and hierarchies or nodes to be excluded from a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
1. Click **Save**.

## Related Resources

- [Promotion Management Overview](/docs/commerce-manager/promotions-standard/overview)
- [Customers](/docs/customer-management/customers)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

---

## Creating Item Percentage Discount Promotions

:::caution
We recommend to use **Advanced (Conditions v2)** settings.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. In the **Name** field, enter a name for the promotion.
1. In the **Description** field, enter a description for the promotion.
1. In the **Start date**  field, select the start time for the promotion.
1. In the **End date** field, the end time of the promotion.
1. To enable the promotion, select the **Enabled** field.
1. (Optional) To automatically apply the promotion, select the **Automatic** field.

    If this field is not selected, the promotion requires the buyer to enter a code in the cart to get the discount. For more information, see the [Adding codes](/docs/commerce-manager/promotions-standard/overview#creating-promotion-codes) section.
1. (Optional) In the **Minimum cart value** field, click **Specify values**.
   The **Set minimum cart value** window is displayed.
   1. In the **Amount** field, enter a minimum cart value before the promotion can be applied.
   1. In the **Select currency** field, select a currency.
      You can add one or several value specifications in different currencies. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
    1. Click **Save**.
1. (Optional) In the **Maximum discount value** field, enter the maximum possible discount amount and currency.
1. In the **Promotion type** field, select **Item percent discount**.
1. (Optional) In the **Quantity limit per use** field, specify the maximum number of application of a promotion per cart for a single use of a promotion.

    Each unique product in the cart will qualify for a promotion for X number of times depending upon what you specified in the **Quantity limit per use** field. For example, if the **Quantity limit per use** field is set to 1, and *SKU A* and *SKU B* are in the cart with a quantity of two each, only one instance of each *SKU A* and *SKU B* will qualify for a promotion.
1. In the **Define schema** section, do the following:
    1. Click **Add percentage**.

        The **Add currency** window is displayed.
    1. In the **Percentage** field, enter percentage to be included for the promotion.

        You can add up to six decimal places for the percentage to be applied for the promotion.
    1. Click **Save**.
    1. In the **Catalogs** field, select the catalogs to be applied for this promotion from the list.

        If you do not select any catalogs from the list, all catalogs will be applied for the promotion.
    1. (Optional) In the **Targets** section, to enable the promotion for all products, click the **Apply to all products** toggle.
    1. In the **Promotion Conditions** subsection:

        1. To include products in a promotion, do the following:
            1. Go to **Products**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **SKUs or Product IDs** to be included in a promotion.
            1. Click **Add Condition**.
        1. To include attributes and hierarchies or nodes in a promotion, do the following:
            1. Go to **Simplified (Conditions v1)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be included in a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to include in a promotion in the **Hierarchy / Nodes UUIDs** field, and then click **Add Condition**.
        1. To include attributes and hierarchies or nodes in a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be included in a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to include in a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be included in a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes, and hierarchies or nodes to be included in a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
    1. In the **Promotion Exclusions** subsection:
            :::caution
             **Promotion Exclusions** subsection is enabled only when you update the **Simplified (Conditions v1)** or **Advanced (Conditions v2)** settings in the **Promotion Conditions** subsection.
            :::
        1. To exclude products from a promotion, do the following:
            1. Go to **Products**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **SKUs or Product IDs** to be excluded from a promotion.
            1. Click **Add Condition**.
        1. To exclude attributes and hierarchies or nodes from a promotion, do the following:
            1. Go to **Simplified (Conditions v1)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
        1. To exclude attributes and hierarchies or nodes from a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be excluded from a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes, and hierarchies or nodes to be excluded from a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
1. Click **Save**.

## Related Resources

- [Promotion Management Overview](/docs/commerce-manager/promotions-standard/overview)
- [Customers](/docs/customer-management/customers)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

---

## Creating X for Amount Discount Promotions

Use this procedure to create promotions such as, such as *3-for-$20* sales. In this promotion, 3 SKU1s are sold for $20.

:::caution
- We recommend not to set maximum discount value for this promotions. Setting maximum discount value for this promotion conflicts with the promotion settings.
- We recommend to use **Advanced (Conditions v2)** settings.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. In the **Name** field, enter a name for the promotion.
1. In the **Description** field, enter a description for the promotion.
1. In the **Date range**  field, select the start date and time and the end date and time of the promotion.
1. To enable the promotion, click the **Enabled** toggle.
1. (Optional) To automatically apply the promotion, click the **Automatic** toggle.

    If this field is not selected, the promotion requires the buyer to enter a code in the cart to get the discount. For more information, see the [Adding codes](/docs/commerce-manager/promotions-standard/overview#creating-promotion-codes) section.
1. (Optional) In the **Minimum cart value** field, click **Specify values**.

    The **Set minimum cart value** window is displayed.
      1. In the **Amount** field, enter a minimum cart value before the promotion can be applied
      1. In the **Select currency** field, select a currency.
      You can add one or several value specifications in different currencies. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
      1. Click **Save**.
1. In the **Promotion type** field, select **X for amount**.
1. (Optional) In the **Quantity limit per use** field, specify the maximum number of application of a promotion per cart for a single use of a promotion.

    Each unique product in the cart will qualify for a promotion for X number of times depending upon what you specified in the **Quantity limit per use** field. For example, if the **Quantity limit per use** field is set to 1, and *SKU A* and *SKU B* are in the cart with a quantity of two each, only one instance of each *SKU A* and *SKU B* will qualify for a promotion.
1. In the **Define schema** section, do the following.
    1. In the **Currencies** subsection:
        1. Click **Add currency**.
        1. In the **Amount** field, enter the promotion amount.
        1. In the **Select currency** field, select a currency from the list.
        1. Click **Save**.
    1. In the **Catalogs** field, select the catalogs to be applied for this promotion from the list.

        If you do not select any catalogs from the list, all catalogs will be applied for the promotion.
    1. In the **X/Y values** subsection:
        1. Click **Specify X/Y values**.

            The **Add X Value** window is displayed.
        1. In the **X value** field, specify the values for X.
        1. Click **Save**.
    1. In the **Promotion Conditions** subsection:

        1. To include products in a promotion, do the following:
            1. Go to **Products**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **SKUs or Product IDs** to be included in a promotion.
            1. Click **Add Condition**.
        1. To include attributes and hierarchies or nodes in a promotion, do the following:
            1. Go to **Simplified (Conditions v1)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be included in a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to include in a promotion in the **Hierarchy / Nodes UUIDs** field, and then click **Add Condition**.
        1. To include attributes and hierarchies or nodes in a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be included in a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to include in a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be included in a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes and hierarchies or nodes to be included in a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
    1. In the **Promotion Exclusions** subsection:
            :::caution
             **Promotion Exclusions** subsection is enabled only when you update the **Simplified (Conditions v1)** or **Advanced (Conditions v2)** settings in the **Promotion Conditions** subsection.
            :::
        1. To exclude products from a promotion, do the following:
            1. Go to **Products**.
            1. Click **Add exclude**.
            1. In the **Condition Type** field, choose **SKUs or Product IDs** to be excluded from a promotion.
            1. Click **Add Condition**.
        1. To exclude attributes and hierarchies or nodes from a promotion, do the following:
            1. Go to **Simplified (Conditions v1)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
        1. To exclude attributes and hierarchies or nodes from a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. lick **+AND** to add another condition on attributes, and hierarchies or nodes to be excluded from a promotion
            1. Click **+OR** to add multiple *OR* conditions on attributes and hierarchies or nodes to be excluded from a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
1. Click **Save**.

## Related Resources

- [Promotion Management Overview](/docs/commerce-manager/promotions-standard/overview)
- [Customers](/docs/customer-management/customers)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

---

## Creating X for Y Discount Promotions

Use this procedure to create promotions such as, such as *2-for-1* sales. In this promotion, 2 SKU1s are sold for the price of 1. In this example, X is 2 and Y is 1.

:::caution
- We recommend not to set maximum discount value for this promotions. Setting maximum discount value for this promotion conflicts with the promotion settings.
- We recommend to use **Advanced (Conditions v2)** settings.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. In the **Name** field, enter a name for the promotion.
1. In the **Description** field, enter a description for the promotion.
1. In the **Date range**  field, select the start date and time and the end date and time of the promotion.
1. To enable the promotion, click the **Enabled** toggle.
1. (Optional) To automatically apply the promotion, click the **Automatic** toggle.

    If this field is not selected, the promotion requires the buyer to enter a code in the cart to get the discount. For more information, see the [Adding codes](/docs/commerce-manager/promotions-standard/overview#creating-promotion-codes) section.
1. (Optional) In the **Minimum cart value** section, click **Add minimum cart value**.

    The **Set minimum cart value** window is displayed.
      1. In the **Amount** field, enter a minimum cart value before the promotion can be applied
      1. In the **Select currency** field, select a currency.
      You can add one or several value specifications in different currencies. For more information about currencies, see the [Managing Currencies in Commerce Manager](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) section.
      1. Click **Save**.
1. In the **Promotion type** field, select **X for Y**.
1. (Optional) In the **Quantity limit per use** field, specify the maximum number of application of a promotion per cart for a single use of a promotion.

    Each unique product in the cart will qualify for a promotion for X number of times depending upon what you specified in the **Quantity limit per use** field. For example, if the **Quantity limit per use** field is set to 1, and *SKU A* and *SKU B* are in the cart with a quantity of two each, only one instance of each *SKU A* and *SKU B* will qualify for a promotion.

1. In the **Define schema** section, do the following.
    1. In the **X/Y values** subsection:
        1. Click **Specify X/Y values**.

            The **Add X and Y Value** window is displayed.
        1. In the **X value** and **Y value** fields, specify the values for X and Y.

            For example, for a promotion 2 for 1, **X value** is 2 and **Y value** is 1.
        1. Click **Save**.
    1. In the **Catalogs** field, select the catalogs to be applied for this promotion from the list.

       If you do not select any catalogs from the list, all catalogs will be applied for the promotion.
    1. In the **Promotion Conditions** subsection:

        1. To include products in a promotion, do the following:
            1. Go to **Products**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **SKUs or Product IDs** to be included in a promotion.
            1. Click **Add Condition**.
        1. To include attributes and hierarchies or nodes in a promotion, do the following:
            1. Go to **Simplified (Conditions v1)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be included in a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to include in a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
        1. To include attributes and hierarchies or nodes in a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be included in a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to include in a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be included in a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes and hierarchies or nodes to be included in a promotion.
                    :::note
                    Under **Advanced (Conditions v2)** settings:
                    - You can add up to five **+AND** conditions inside the per **+OR** condition.
                    - You can include up to 10 **+OR** conditions.
                    :::
    1. In the **Promotion Exclusions** subsection:
            :::caution
             **Promotion Exclusions** subsection is enabled only when you update the **Simplified (Conditions v1)** or **Advanced (Conditions v2)** settings in the **Promotion Conditions** subsection.
            :::
        1. To exclude products from a promotion, do the following:
            1. Go to **Products**.
            1. Click **Add exclude**.
            1. In the **Condition Type** field, choose **SKUs or Product IDs** to be excluded from a promotion.
            1. Click **Add Condition**.
        1. To exclude attributes and hierarchies or nodes from a promotion, do the following:
            1. Go to **Simplified (Conditions v1)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
        1. To exclude attributes and hierarchies or nodes from a promotion based on multiple conditions at the same time, do the following:
            1. Go to **Advanced (Conditions v2)**.
            1. Click **Add Promotion Condition**.
            1. In the **Condition Type** field, choose **Attributes** or **Hierarchy or Nodes** to be excluded from a promotion.
            1. If you chose **Attributes**, choose the **Template Slug** and **Attribute slug** from the list, enter **Attribute Value**, and then click **Add Condition**.
            1. If you chose **Hierarchies or Nodes**, enter the IDs of the hierarchies or nodes that you want to exclude from a promotion in the **Hierarchy/Nodes UUIDs** field, and then click **Add Condition**.
            1. Click **+AND** to add another condition on attributes, and hierarchies or nodes to be excluded from a promotion.
            1. Click **+OR** to add multiple *OR* conditions on attributes, and hierarchies or nodes to be excluded from a promotion.
                :::note
                Under **Advanced (Conditions v2)** settings:
                - You can add up to five **+AND** conditions inside the per **+OR** condition.
                - You can include up to 10 **+OR** conditions.
                :::
1. Click **Save**.

## Related Resources

- [Promotion Management Overview](/docs/commerce-manager/promotions-standard/overview)
- [Customers](/docs/customer-management/customers)
- [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration)

---

## Promotions Standard(Promotions-standard)

import Video from "/src/components/CardDisplay/video"

You can manage promotions on the **Merchandise > Promotions > Standard** page.

## Creating Promotions

:::caution
- You cannot change the promotion type or schema after creating a promotion.
- If you want to restrict the usage of a promotion, do not select the **Automatic** field in promotion setting and ensure that you create a code for the promotion.
- You can use product ID instead of product SKU to specify products.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**. Click **Add promotion**.
1. Enter the the required information to create the following promotions:

    - [Cart-level fixed discount promotions](/docs/commerce-manager/promotions-standard/cart-level-promotions/cart-level-fixed-discount)
    - [Cart-level percentage discount promotions](/docs/commerce-manager/promotions-standard/cart-level-promotions/cart-level-percentage-discount)
    - [X for Y discount promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/x-for-y-discount-promotions)
    - [X for amount discount promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/x-for-amount-discount-promotions)
    - [Bundle discount promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/bundle-discount-promotions)
    - [Item fixed discount promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/item-fixed-discount-promotions)
    - [Item percentage discount Promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/item-percentage-discount-promotions)
    - [Free gift promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/free-gift-promotions)

:::caution
- We recommend not to use the **Maximum discount value** setting for the following promotions:

    - [Cart-level fixed discount promotions](/docs/commerce-manager/promotions-standard/cart-level-promotions/cart-level-fixed-discount)
    - [Item fixed discount promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/item-fixed-discount-promotions)
    - [X for Y discount promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/x-for-y-discount-promotions)
    - [X for amount discount promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/x-for-amount-discount-promotions)
    - [Bundle discount promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/bundle-discount-promotions)
    - [Free gift promotions](/docs/commerce-manager/promotions-standard/item-level-promotions/free-gift-promotions)

- The **Promotion Exclusions** setting specifies the products to be excluded from the cart-level promotions, such as `fixed_discount` and `percent_discount`. However, the stores that use [simple calculation method](/docs/api/settings/settings-introduction#calculation-method) do not support excluding products from promotions.
- Line-item discounts are only supported by the line calculation method. For more information about this method, see the [Calculation Method](/docs/api/settings/settings-introduction#calculation-method) section.
:::

## Creating Promotion Codes

After creating a promotion, you can add codes for the promotion. Customers must enter this code to avail the promotion. For the code to work, ensure that the **Automatic** field in the promotion settings is not selected.

1. Navigate to **STORE > Promotions Standard**.
1. Select the promotion for which you want to create a code.
1. Go to the **Promotion Codes** tab.

    The **Promotion Codes** tab displays the following information:

    - **Code ID**
    - **Usage limit type**
    - **Remaining Uses**
    - **Max Uses**
    - **Creation Date**
    - **Restrictions**
    - **Actions**

1. On the right-hand side, click **Add a new promotion code**.
1. Click one of the following tabs:

    - [**Add a single code**](#adding-single-code)
    - [**Bulk generate codes**](#generating-bulk-codes)

1. Enter the required settings.
1. Click **Save**.

### Adding a single code

To add a new promotion code, follow these steps:

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**.
1. Select the promotion for which you want to create a code.
1. Go to the **Promotion Codes** tab.
1. On the right-hand side, click **Add a new promotion code**.
1. In the **Add a single code** tab, enter the following details:

    - **Usage limit type** : Choose whether the usage limitation is at the item-level or cart-level. The options are **Per Cart** and **Per Line Item**.
    - (Optional) **Maximum uses** : Enter the maximum the number of times a code can be used for this promotion. If no value is set, customers can use unlimited number of times. We recommend you to set value greater than or equal to 1.
    - (Optional) **Restrict to user** : Enter the customer ID of users who are allowed to use this code.
    - **Code** : Define the code for the promotion. You can manually enter the code.

1. Click **Save**.

### Generating bulk codes

:::caution
- You can only generate a maximum of 1000 codes for a single promotion.
- When generating more than 1000 codes, the promotion's duration must be limited to a maximum of 365 days from its start date. If you need to increase the number of promotion codes for a single promotion, reach out to our [customer success team](mailto:customersuccess@elasticpath.com).
:::

With bulk generating codes, you can generate large number of unique promotion codes. To do so, follow these steps:

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**.
1. Select the promotion name for which you want to create codes.
1. Go to the **Promotion Codes** tab.
1. On the right-hand side, click **Add a new promotion code**.
1. In the **Bulk generate codes** tab, enter the following details:

    - **Number of codes to generate** : Specify the number of codes to be generated.
    - **Code Length** : Specify the desired code length, which ranges from 8 to 16 characters. The default code length is eight characters, and a dash is added after every four characters in the code. For example, *aa2b-3c4d*.
    - (Optional) **Promotion End Date** : This field appears when the promotion's expiration date extends beyond a year. The promotion expiry date must be 365 days. Therefore, you are required to set the end date and time for the promotion in such cases. Under **Quick End Date Select**, choose **From today's date** if you want to start the promotion today or **From promotion start date** if you want to start the promotion in the future.
    - (Optional) **Usage Limit Type** : Indicate whether the usage limitation is at the item-level or cart-level. The options are **Per Cart** and **Per Line Item**.
    - (Optional) **Maximum uses** : Enter the maximum number of usages of a code for a promotion. If no value is set, customers can use the code unlimited number of times. We recommend you to set value greater than or equal to 1.
    - (Optional) **Prepend Value** : Add a prefix value to the generated codes. When codes are generated, the specified prepend value is added as a prefix to each code. For example, if you set *summer* as prepend value and *aa2b-3c4d* is generated, the promotion code is *summer-aa2b-3c4d*.
    - (Optional) **Code Group Name** : Enter the name for the job invoked to generate the code. See [Create a Job](/docs/api/promotions/create-a-promotion-job).

1. Click **Save**.

    The codes generated for a promotion are displayed on the details page of the promotion.

    :::caution
    Refresh your Commerce Manager to view the generated codes on the **Promotions Codes** tab.
    :::

## Searching a Promotion Code

You can find a promotion code within all promotions or within a specific promotion.

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**.
1. If you want to search within a specific promotion, click the promotion name and go to the **Promotion Codes** tab.
1. In the **Search coupon code** field, enter the promotion code that you want to find.

    The promotion code within a specific promotion is displayed.
1. If you want to search within all promotions, go to **STORE > Promotions** and directly enter the promotion code in the **Search coupon code** field.

    The promotion name that contains the associated promotion code is displayed.

## Deleting a Code

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**.
1. Click the promotion name for which you want to add a code.
1. Go to the **Promotion Codes** tab.
1. Select the **CodeID** that you want to delete.
1. In the **Actions** column, click the ellipsis associated with the **CodeID** and select **Delete** to delete the code.

## Duplicating Promotions

You can duplicate an existing promotion and use the details as required in another promotion. However, the **Date range** field is not duplicated.

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**.
1. To duplicate a promotion, do one of the following:
    - In the **Actions** column, under the list of **All Promotions**, click the ellipsis associated with **Name** of the promotion and select **Duplicate**.
    - Open the promotion that you want to duplicate and click **Action > Duplicate** at the end of the page.

    The selected promotion is duplicated and opened in a new tab with the following details:

    - The name of the source promotion is duplicated with the suffix, *-copy*. For example, *50% off order - copy*.
    - The description of the source promotion is duplicated with the suffix, *-copy*. For example, *This promotion is to give 50% off on an order- copy*.
    - The default status of the duplicated promotion is always **Disabled**.
    - If the source promotion is applied automatically, the automatic status is duplicated and new promotions code is auto-generated.
    - Minimum cart value, maximum discount value, promotion type, schema, and custom field settings are duplicated.
1. Make the required changes and click **Save**.

## Editing Promotions

:::caution
- You cannot change the promotion type or schema after creating a promotion.
- Any changes made to the active and enabled promotion can impact an active promotion that has been already applied to a cart. For example, switching the promotion from automatic to manual, adjusting the discount amount, extending the promotion date, or modifying the schema.
:::

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**.
1. Click the promotion name that you want to edit.
1. Change the settings as required.
1. Click **Save**.

## Viewing Promotion History

The **History** tab provides version history of a promotion You can view the version details except changes in the promotion code and custom fields, of each version.

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**.
1. To view history of a promotion, click the promotion name.
1. Click the **History** tab.
    A list of versions with the following information about each version is displayed:

    - **Date / Time**: Date and time when the update in made in the promotion.
    - **Updated Fields**: The name of the fields that are updated in the corresponding version.
    - **Actions**: An option to view the details of the selected version. You can only view the details in the **Version Details** tab. You cannot edit the details.

The history table displays the latest edit first and earliest original last. For any changes in the promotion codes and custom fields of the promotion, the **Updated Fields** displays *Promotion codes and/or custom fields* value. However, when you click **Actions** to view the details, the **Version Details** tab does not reflect the changes.

## Managing Code Export

Using the **Manage Code Export** tab, you can export your promotion codes and download them in CSV format. To do so, follow these steps:

1. In Commerce Manager, go to **Merchandise > Promotions > Standard**.
1. Select the promotion name for which you want to export the codes.
1. Go to the **Promotion Codes** tab.
1. On the right side, click **Manage Code Export**.
1. Click **Create export** to initiate the code export process.

    Once the export is completed, you can download the exported file in CSV format.

## Related Resources

- [Promotions Standard](/docs/api/promotions/promotions-standard-introduction)
- [Customers and Accounts](/docs/api/accounts/account-management-introduction)
- [Catalog](/docs/api/pxm/catalog)
- [Create a Job](/docs/api/exporter/create-job)

### Demos

- <Video
  mediaSrc="https://www.youtube.com/embed/MQTrLZp3cjI"
  mediaType="embed"
  title="Configuring a Promotion" />
- <Video
  mediaSrc="https://www.youtube.com/embed/fyQV8YWj4os"
  mediaType="embed"
  title="Configuring a Hierarchy-Based Promotion" />
- <Video
  mediaSrc="https://www.youtube.com/embed/x7TP4dsjNYs"
  mediaType="embed"
  title="Configuring an AND/OR Promotion Conditions" />

---

## General Settings

## Renaming a Store

Sellers with `Seller Admin` role can rename a store.

1. Go to the **SYSTEM > Store Settings > General Settings** tab.
1. Select **Store** from the drop-down list.
1. In the **Store Name** field, enter the new name for your store.

    You can also view **Store ID**, **Created on**, and **Requests per second** details of your store.

1. Click **Save**.

## Updating PXM Settings to Publish Store Catalogs containing Organizational Resources

1. Go to the **SYSTEM > Store Settings > General Settings** tab.
1. Select **PXM** from the drop-down list.
1. Select the **Include Organization Resources in Catalog Publishes** checkbox to publish the catalogs with organizational resources.

## Updating Cart Settings

By default, carts are automatically removed seven days after the last update. However, you can change this setting in Commerce Manager.

1. Go to the **SYSTEM > Store Settings > General Settings** tab.
1. Select **Orders & Carts** from the drop-down list.
1. In the **Cart Expiration** field, enter a number between 1 and 365 corresponding to the number of days after which the cart expires.

    The default setting is updated with the new value.

## Updating Customer and Accounts Settings

### Updating Account Membership Settings

1. Go to the **SYSTEM > Store Settings > General Settings** tab.
1. Select **Customers & Accounts** from the drop-down list.
1. In **Membership Limit**, under **Account Membership Settings**, update the membership limit that is the number of accounts an account member can be associated with. You can set this value to any number up to 10,000.

### Viewing and Changing Time to Live Settings

1. Go to the **SYSTEM > Store Settings > General Settings** tab.
1. Select **Customers & Accounts** from the drop-down list.
1. In **Time to live**, under **Personal Data Settings**, the current number of days is displayed.
1. To change the number of days, type the new number of days.
1. Click **Save**.

### Updating Address Form Settings

Sellers with `Seller Admin` can update the Mandatory Address Fields. For example, you may want to use the `Region` field as required and switch `County` to be optional.

1. Go to the **SYSTEM** > **Store Settings** > **General Settings** tab.
1. Select **Customers & Accounts** from the drop-down list.
1. In the **Customers/Accounts Address Form Settings** table, select the required vs optional fields to be set.
1. Click **Save**.

---

## Configuring Billing & Payments

You can configure schedules for your billing and payment runs. By scheduling billing and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner. 

## Schedules

You can define a schedule in the format (* * * * *) which is a set of five fields in a line, indicating when a job should be executed. For example, you can define a schedule so that your job runs multiple times a day, or runs on specific days and months.

### Unrestricted fields

Setting a field to an asterisk (`*`) is sometimes referred to as leaving a field unrestricted because it is not restricted to a specific value.
      
You can use the asterisk (`*`) to indicate the range of all values for the field. When you use the asterisk, the first value in the range is: 0 for the minute, hour, and day of the week (Sunday) fields, and 1 for day of the month and the month fields.
      
### Configuring fields
      
The time fields have the following format and possible values and must be specified in the following order:
      
| Field | Format | Description  |                                                                                                    
| --- | --- | -----|
| Minute | 0-59 | Indicates how far past the top of the hour your job runs, in minutes. For example if a minute is set to 0, then the job runs at the top of the hour because it is 0 minutes after the hour. This means if the hour is 8.00 AM, the job runs at 8.00 AM. |
| Hour | 0-23 | Indicates how far past midnight your job runs, in hours. This is rounded down to the nearest hours. This is because minutes are indicated by the minute field. |
| Day of the month | 0-31 | Indicates the calendar date of the month. For example, 1 for the first day of the month. |
| Month | 1-12 or JAN to DEC | Indicates the month. Specify the month number or the first three letters of the month name in uppercase. For example, 1 or JAN for January.  |
| Day of the week | 0-6 (or SUN to SAT, or 7 for Sunday) | Indicates the day of the week. Monday is 1, Tuesday is 2, and so on. Either 0 or 7 indicates Sunday. Alternatively, specify the day of the week using the first three letters of the weekday name in uppercase. For example SUN for Sunday. If you use this field with the day of the month field, then this field is evaluated as an inclusive OR. For example, if the day of the month is set to 1 and the day of the week is set to SAT, the job runs on the first day of the month and on every Saturday of the month, even if the first day of the month is not a Saturday. If the day of the week is marked by an asterisk (*) then the field is marked as unrestricted. This means the job only runs on the first day of the month. |
      
### Matching all values
      
To match all values for a field, set the field to an asterisk (`*`). When a field is set to an asterisk, the field matches all valid values for that field whenever the other field conditions are satisfied. 
      
Here are some examples.

- `30 0 * * *`: the job runs every day at 12:30am.
- `0 16 * * 1`: the job runs once a week at 4pm on a Monday.

### Matching a range
      
To match a range of values, specify your start and stop values, separated by a hyphen (`-`). Do not include spaces in the range. Ranges are inclusive. The first number must be less than the second number. If you are using abbreviated names for the month or weekday (for example, JAN instead of 1 for the first month of the year), the first value must come earlier in the month or week than the second value.

The following equivalent examples run at midnight on Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays (for all months):

- `0 0 * * 1-5`
- `0 0 * * MON-FRI`

### Matching a list
      
Lists can contain any valid value for the field, including ranges. Specify your values, separated by a comma (,). Do not include spaces in the list.

Examples:

- `0 0,12 * * *`: the job runs at midnight and noon.
- `0-5,30-35 * * * *`: the job runs in each of the first five minutes of every half hour (at the top of the hour and at half past the hour).
      
### Skipping values in a range
      
You can skip values in a range by specifying a rate at which to step through the range. To do this, specify the range, followed by the forward slash (`/`) and the rate at which you want to skip through the range.
      
The step value cannot be larger than the largest possible value for the field. The default step is 1, so the step function `/1` is the same as not using a step function at all.

Example ranges that use step functions:

- `*/2`: this is a valid step function for any field. 
    - For the minute field, it matches 0, 2, 4, ... , 58. 
    - For the hour, it matches 0, 2, 4, ... , 22. 
    - For the day of the month, it matches 1, 3, 5, ... , 31 (for a month with 31 days). 
    - For the month, it matches 1, 3, 5, ... , 11. 
    - For the day of the week, it matches 0, 2, 4, 6.

- `0-12/2`: this is a valid step function for the minute and hour fields. It matches 0, 2, 4, ... , 12.

Example schedules using step functions:
      
- `*/2 * * * *`: the job runs every two minutes.
- `0 0-12/2 * * *`: the job runs every two hours, on the hour. The first run is at midnight. The last run is at noon.

## Configuring Billing & Payment Runs

The following steps describe how to configure billing and payment runs.

1. Log in to Commerce Manager.
2. Go to **SUBSCRIPTIONS** > **Billing & Payments**. 
3. Select **Configure** > **Manage Schedules**.
4. Select **Configure New Schedule**.
5. You can select either:

    - **Guided options**. Select this if you want to schedule your billing and payment runs to  occur on a weekly, monthly, or yearly basis.

     | Option                      | Required | Description                                                                                                                                                                             |
     |-----------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
     | **Name**                    | Required | The name of the schedule.                                                                                                                                                               |
     | **Select Payment Run Type** | Required | The payment type you are scheduling. Must be either **Payment Run** or **Billing Run**.                                                                                                 |
     | **External Reference**      | Optional | A unique reference that you could use to contain information from another company system, for example.                                                                                  |
     | **Location**                | Required | The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) and conforms to [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339). |
     | **Select a frequency**      | Required | Select either:WeeklyHoursMinutes                                                                                                                    |

    - **Advanced options (Crontab)**. Select this if you require your billing and payment runs to occur on a more precise basis, such as at specific time and day of every month.

     | Option                      | Required | Description                                                                                                                                                                                                                                                                                 |
     |-----------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
     | **Name**                    | Required | The name of the schedule.                                                                                                                                                                                                                                                                   |
     | **Select Payment Run Type** | Required | The payment type you are scheduling. Must be either **Payment Run** or **Billing Run**.                                                                                                                                                                                                     |
     | **External Reference**      | Optional | A unique reference that you could use to contain information from another company system, for example.                                                                                                                                                                                      |
     | **Location**                | Required | The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) and conforms to [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339).                                                                                                     |
     | Configure your crontab      | Required | You can define a schedule in the format (* * * * *) which is a set of five fields in a line, indicating when a job should be executed. For example, you can define a schedule so that your job runs multiple times a day, or runs on specific days and months. See [Schedules](#schedules). |
6. Select **Save**.

![billing run schedule example](/assets/subscription-schedule.png)

---

## Overview(Billings-payments)

Elastic Path Subscriptions enables you to manage the billing and recurring payments associated with your customers subscriptions. Billing runs generate [invoices](#invoices) for your customers. Payment runs automatically process payments against those invoices.

## Invoices

Invoices represent the amount a customer owes for a subscription. Elastic Path Subscriptions generates an invoice for every period in a subscription billing cycle. Invoices provide:

- an itemized list of goods and services provided by a subscription.
- the cost of a subscription.
- if applicable, any taxes.

Subscriptions automatically generates an invoice for each billing cycle and initiates payment using billing and payment runs.

### Invoice Lifecycle

The invoice lifecycle is described below.

1. When a subscription is created, an invoice for the first billing period is created. When a subscription is created as part of an order, the payment for the order covers the first billing period.
1. Subscription invoices are created by billing runs. The billing run identifies subscriptions that require a new invoice for their next billing period and creates them. At this point, invoices are marked as `outstanding`.
1. The payment run identifies invoices that are still outstanding and attempts to take payment for them. If the payment succeeds then the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment.

## Billing & Payments Jobs

Billing and payment runs function as jobs. There are two types of job:

- a billing run. Subscriptions generates an invoice when a billing run occurs. Billing runs generate invoices for the remaining billing cycles for each subscription. The invoice dates come from your plans. Billing runs are independent of payment runs.
- a payment run. The payment run identifies invoices that are `outstanding` and attempts to take payment for them. If the payment succeeds then the invoice is no longer `outstanding`. If the payment fails for any reason, then the invoice remains `outstanding` and is picked up by the next payment run to retry the payment.

Jobs can be scheduled. By scheduling billing and payment runs, you automate the process, reducing manual intervention and ensuring the jobs are run in a timely manner. See [Schedules](/docs/commerce-manager/subscriptions/billings-payments/configuring-runs#schedules).

### Characteristics of Billing & Payments Jobs

Billing and payment jobs have the following characteristics.

- Jobs are asynchronous.
- Billing and payment jobs work concurrently.
- Jobs have a different status, depending on where a job is in its lifecycle. See [Managing Billing & Payments](/docs/commerce-manager/subscriptions/billings-payments/updating-runs).
- Jobs report any errors to help you understand the reason for any failed jobs. See [Managing Billing & Payments](/docs/commerce-manager/subscriptions/billings-payments/updating-runs)
- Only one billing run and payment run is allowed per store at a time. Although billing and payments are constantly generated, the jobs are queued. Subscriptions looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed.

---

## Managing Billing & Payments

Once your billing and payment runs have completed, you can view them in **Billing & Payments**. For example, you may want to check the status of the billing and payment runs, or update any existing schedules.

## Managing Billing & Payment Runs

The following steps describe how to manage billing and payment runs.

1. Log in to Commerce Manager.
2. Go to **SUBSCRIPTIONS** > **Billing & Payments**. A list of completed billing and payment runs is displayed. 
    - Select **Schedule ID** to view/update the schedule for a billing or payment run. See [Schedules](/docs/commerce-manager/subscriptions/billings-payments/configuring-runs#schedules).
    - view the current status of your billing and payment runs.
       - **Pending** - Subscriptions has received the request but is currently busy processing other requests.
       - **Started** - Subscriptions has started processing the job.
       - **Complete** - The job has successfully completed.
       - **Failed** - The job has failed. 
    - You can delete one or more of the billing and payment runs by checking the box next to the billing and payment run you want to delete and selecting **Actions** > **Delete**.
    - Troubleshoot any errors the payment or billing run may have received.

---

## Creating Dunning Rules

Subscriptions enables you to create a dunning rule that allows you to configure payment retry schedules. Subscriptions retries failed payments automatically. You can customize the timing and frequency of the payment retries.

Dunning is enabled by default. If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments.

If you configure a dunning rule, the dunning rule becomes the default for your store. All invoices in your store will then perform dunning according to the specified rules.

1. Go to **Subscriptions** > **Dunning and Prorations**.
2. Select **Dunning Rulesets**.
3. Configure the following:

    | Option             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
    |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | Retry payment unit | The unit of time used to measure the intervals between payment attempts or retries, days or weeks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
    | Retry payment interval | The number of retry payment units (for example, days or weeks) to wait between each payment retry attempt                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
    | Retry payment limit | The number of times subscriptions attempts payments retries before an action is taken.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
    | Action | The action to take if payment is not successful. You have the following options: Keep active - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.Paused -  the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.Closed -  the subscription ends and it's status becomes inactive. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment. |
4. Select **Save**.
5. You can update the dunning rule at anytime.

---

## Overview(Dunning)

Dunning is the process of handling failed payment attempts. This is important for recovering revenue from failed payments, reduces customer churn and maintains cashflow. By implementing efficient dunning processes, you can enhance financial health and operational efficiency.

Subscriptions enables you to create a dunning rule that allows you to configure payment retry schedules. Subscriptions retries failed payments automatically. You can customize the timing and frequency of the payment retries.

Dunning is enabled by default. You can choose to disable dunning. If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments.

- Do nothing - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.
- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.
- close a subscription. The subscription ends and it's status becomes inactive. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.

---

## Creating Proration Policies

In Subscriptions, you configure proration by creating a proration policy and applying it to an offering. Once you have applied the policy, the proration policy applies to all subscriptions that use the offering.

1. Go to **Subscriptions** > **Dunning and Prorations**.
2. Select **Proration Policies**.
3. Select **Create New Proration Policy**.
4. Configure the following:
    
    | Option | Description                                                                                                                                                                                                                                                                                                                                                                                                   |
    |--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Name** | A name for the policy.                                                                                                                                                                                                                                                                                                                                                                                        | 
    | Rounding | You can: round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use.round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use.round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down. |

5. Select **Save**.
6. To apply a proration policy to an offering, go to **Subscriptions** > **Offerings**.
7. From **All Offerings**, select the offering to which you want to apply a proration policy. You can select more than one.
8. In **Proration Policy** list, select the proration policy you want to apply.
9. Select **Save Offering**.

---

## Deleting Proration Policies

A proration policy cannot be deleted if it is being used by any subscriptions. This means you must remove a proration policy that you want to delete from any offerings using that policy before deleting the policy. 

To delete a proration policy:

1. To remove a proration policy from an offering, go to **Subscriptions** > **Offerings**.
2. From **All Offerings**, select the offering to which you want to remove a proration policy. 
3. In **Proration Policy** list, either select another proration policy or select **No proration policy**. 
4. Select **Save Offering**.
5. Go to **Subscriptions** > **Dunning and Prorations**.
6. Select **Proration Policies**.
7. Select the proration policy you want to delete. 
8. Select ![trash icon](/assets/trash-icon.png).
9. Select **Delete** to close the **Delete Proration Policy Confirmation** dialog and delete the policy.

---

## Overview(Proration)

Proration is the adjustment of charges or credits on a subscribers account based on the amount of time a service is used. Proration ensures that subscribers are only charged for the actual time they use the service, whether they upgrade, downgrade, start, or cancel their subscription partway through a billing cycle. This means fair billing for your subscribers and provides you with the flexibility to change your subscribers subscriptions at any time.

Proration occurs for:

- Product additions/deletions: If a subscriber adds or removes products to their subscription in the middle of a billing cycle, proration adjusts the charges to reflect the product changes.
- Plan upgrades/downgrades: If a subscriber changes their plan in the middle of a billing cycle, proration adjusts the charges to reflect the time spent on each plan.
- Service cancellation: If a subscriber cancels a subscription before the end of a billing cycle, they may receive a prorated refund for the unused portion of the subscription.
- Mid-cycle subscription: If a subscriber starts a subscription in the middle of a billing cycle, they are charged a prorated amount for the remaining days in the billing cycle.
There are several scenarios when implementing proration policies.

There are several scenarios when implementing proration policies.

- You may want one policy for multiple offerings because only some subscriptions need prorating.
- You may want a default proration policy for your store.
- You may want several policies for different offerings.

In Subscriptions, charges only prorate by day. As soon as a subscriber changes their subscription, a manual billing run is triggered and an invoice is generated with the new price on the next billing run and the difference in price is prorated over days.

By default, proration is not enabled for Subscriptions. Once you have applied a proration policy to an offering, proration is enabled automatically. See [Creating Proration Policies](/docs/commerce-manager/subscriptions/dunning-proration/proration/creating-proration).

---

## Updating Proration Policies

You can update a proration policy at any time. For any subscriptions that are using the updated proration policy, the changes are also applied.

To update a proration policy:

1. Go to **Subscriptions** > **Dunning and Prorations**.
2. Select **Proration Policies**.
3. Select the proration policy you want to edit.
4. When updating a proration policy:

    - You can change the name of an existing policy.
    - You can update rounding.
    - You cannot remove any required attributes, such as **Name** or rounding.
    
5. Select **Save**.

---

## Overview(Invoicing)

Elastic Path Subscriptions enables you to manage the billing and recurring payments associated with your customers subscriptions. Billing runs generate [invoices](#invoices) for your customers. Payment runs automatically process payments against those invoices. See [Managing Billing & Payments](/docs/commerce-manager/subscriptions/billings-payments/updating-runs).

## Invoices

Invoices represent the amount a customer owes for a subscription. Elastic Path Subscriptions generates an invoice for every period in a subscription billing cycle. Invoices provide:

- an itemized list of goods and services provided by a subscription.
- the cost of a subscription.
- if applicable, any taxes.

Subscriptions automatically generates an invoice for each billing cycle and initiates payment using billing and payment runs.

## Invoice Lifecycle

The invoice lifecycle is described below.

1. When a subscription is created, an invoice for the first billing period is created. When a subscription is created as part of an order, the payment for the order covers the first billing period.
1. Subscription invoices are created by billing runs. The billing run identifies subscriptions that require a new invoice for their next billing period and creates them. At this point, invoices are marked as `outstanding`.
1. The payment run identifies invoices that are still outstanding and attempts to take payment for them. If the payment succeeds then the invoice is no longer outstanding. If the payment fails for any reason, then the invoice remains outstanding and is picked up by the next payment run to retry the payment.

---

## Viewing Invoices

You can view your invoices in Commerce Manager.

1. To do this, go to **Subscriptions** > **Invoicing**. A list of your invoices is displayed.

    | Option               | Description                                                                                                                                                                              |
    |----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Invoice ID**       | A unique identifier for an invoice.                                                                                                                                                      |
    | **Created**          | The date and time an invoice is created.                                                                                                                                                 |
    | **Subscriber ID**    | The unique identifier of a subscriber who generated an invoice.                                                                                                                          |
    | **Tax Required**     | Whether tax is required for an invoice.                                                                                                                                                  |
    | **Tax Status**       | One of the following: **Tax Applied** - Tax is applied.**Pending Tax** - the tax amount is not yet finalized.**Not Required** - Tax is not required. |
    | **Payment Status**   | One of the following: **Paid** - The invoice is paid.**Unpaid** - payment is outstanding.                                                                     | 
2. Select an invoice to view an invoice's details.

    | Option                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     |
    |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Payment Status**          | One of the following: **Paid** - The invoice is paid.**Unpaid** - payment is outstanding.                                                                                                                                                                                                                                                                                                                            |
    | **Invoice ID**              | A unique identifier for an invoice.                                                                                                                                                                                                                                                                                                                                                                                                             |
    | **Subscription ID**         | A unique identifier for the subscription generating the invoice.                                                                                                                                                                                                                                                                                                                                                                                |
    | **Created**                 | The date and time an invoice is created.                                                                                                                                                                                                                                                                                                                                                                                                        |
    | **Billed to Subscriber**    | The subscriber name, Email address and, ID.                                                                                                                                                                                                                                                                                                                                                                                                     |
    | **Billing Period**          | The billing period start date and end date. See [Creating Plans](/docs/commerce-manager/subscriptions/subscription-plans/creating-plans).                                                                                                                                                                                                                                                              |
    | **Billing Period length**:  | The billing period length. See [Creating Plans](/docs/commerce-manager/subscriptions/subscription-plans/creating-plans).                                                                                                                                                                                                                                                                                                                                                                                                                     |
    | **Tax Required**            | Whether tax is required for an invoice.                                                                                                                                                                                                                                                                                                                                                                                                         |
    | **Tax Status**              | One of the following: **Tax Applied** - Tax is applied.**Pending Tax** - the tax amount is not yet finalized.**Not Required** - Tax is not required.                                                                                                                                                                                                                                                        |
    | **Payment Attempts**        | In Subscriptions, by default, the number of payment retries is 10. You can set this to a limit between 0 - 20, depending on your requirements. Each payment retry is made as a payment run. Once the number of payment retries reaches the limit, the payment retries stop, resulting in the status of the invoice being unpaid. See [Creating Dunning Rules](/docs/commerce-manager/subscriptions/dunning-proration/dunning/creating-dunning). |
    | **Payment ID**                  | A unique identifier for a payment.                                                                                                                                                                                                                                                                                                                                                                                                              |
    | **Payment Status**          | One of the following: **Paid** - The invoice is paid.**Unpaid** - payment is outstanding.                                                                                                                                                                                                                                                                                                                            | 
    | **Report**                      | You can use the report to track your payment operations in Subscriptions. See [Billing, Tax & Payment reports](/docs/api/subscriptions/jobs#billing-tax--payment-reports).                                                                                                                                                                                                                                                                      |
    | **Product Description**         | The description of the subscription product. See [Creating Repeat Products](/docs/commerce-manager/subscriptions/products/creating-products).                                                                                                                                                                                                                                                                                                   |
    | **Pricing**                     | The product price. See [Product Pricing](/docs/commerce-manager/subscriptions/products/managing-products-cm#product-pricing).                                                                                                                                                                                                                                                                                                                   |
    | **Product Price Includes Tax?** | Whether the product price includes tax.                                                                                                                                                                                                                                                                                                                                                                                                         |

---

## Creating Offerings

Follow these steps to create an offering.

:::note
Select **Offering Preview** at any time to view a snapshot of your offering.
:::

1. Log in to Commerce Manager.
2. Select **Subscriptions** **Offerings**.
3. Select **Create New**.
4. (Required) Configure the offering details.

   | Option      | Required | Description                                                  |
   |-------------|----------|--------------------------------------------------------------|
   | Name        | Required | A name for the offering.                                     |
   | Description | Optional | A brief description of the offering to display to customers. |

5. (Required) In **Manage Products**, you can either:

   - [create a new product](/docs/commerce-manager/subscriptions/products/managing-products-cm).
   - attach an existing product. To attach an existing product, select **Attach Product** and select **+** next to the product that you want to attach.
6. (Required) In **Manage Plans**, you can either:

   - [create a new plan](/docs/commerce-manager/subscriptions/subscription-plans/managing-subscription-plans-cm)
   - attach an existing plan. To attach an existing plan, select **Attach Plan** and select **+** next to the plan that you want to attach.

   :::tip
   Select the expanded view to see more product and plan details, for example, product price and subscription cycle, billing frequency, plan pricing and so on.
   :::
7. Select **Save Offering**.
8. You can update an offering at any time by selecting **Subscriptions** > **Offerings** and selecting **...** > **Edit** next to the offering you want to edit.

## Demo

<iframe class="vidyard_iframe"
  mediaType="embed"
  title="Getting Started with Elastic Path Subscriptions" src="//play.vidyard.com/zHF2XPfgFv5gtQSwo8d3mA.html?" width="640" height="360" scrolling="no" frameborder="0" allowtransparency="true" allowfullscreen referrerpolicy="no-referrer-when-downgrade"></iframe>

---

## Deleting Offerings

When a subscription is created, it creates a snapshot of the offering. This means you can delete an offering without affecting any active subscriptions.

1. Select **Subscriptions** > **Offerings**. The **Subscription Offerings** page displays all the offerings that you have created.
2. Either:

   - Select **...** next to any offering that you want to remove, and then select **Delete**.
   - Select the checkbox on an offering that you want to remove and then select **Actions** > **Delete**.

3.Select **Delete** to delete the plan and close the confirmation dialog.

---

## Editing Offerings

Offerings represent a snapshot of their product and plans. If you make updates to a product or plans within an offering, the original product and plans are not updated. Only the product and plans within the offering are updated. Alternatively, you can create a new product and attach it to a new offering.

When you are building an offering:

- you can create new plans and products.
- you can modify an existing product and plans. For example, you can modify the product price or any attributes of a plan included in the offering.

Here's how you build an offering:  

1. Attach your repeat product. An offering can have only one product. See [Repeat Products](/docs/commerce-manager/subscriptions/products/managing-products-cm).
2. Attach your plans. 
    - Plans are the rules that govern your subscription, for example, any discount. 
    - You can combine and reuse plans for as many products as you want, making it quick and easy to create your subscription offerings. 
    - An offering must have at least one plan. See [Plans](/docs/commerce-manager/subscriptions/subscription-plans/managing-subscription-plans-cm).
3. [Create your offerings](/docs/commerce-manager/subscriptions/offerings/managing-subscription-offerings). Offerings are the products and plans that a customer can choose. An offering can consist of many combinations of products or plans, depending on the products and services you offer.
    - When a [customer](/docs/commerce-manager/subscriptions/overview#subscriber-management) chooses a plan, a subscription is created.  
    - Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription. See [Invoicing and Billing](/docs/commerce-manager/subscriptions/billings-payments/overview).

---

## Overview(Offerings)

Offerings represent a snapshot of their product and plans. If you make updates to products or plans within an offering, the original products and plans are not updated. Only the products and plans within the offering are updated. Alternatively, you can create a new product and attach it to a new offering.

An offering includes products and plans; products are combined with one or more plans to form an offering. 

For example, your company provides online streaming of movies, web-series, and music. Your customers can purchase these services through either a weekly or monthly plan.  

![subscription management](/assets/subscription_management.png)

## Offering Examples

Offerings can have any combination of a product and plans. The pricing of an offering is determined by the pricing you have configured for your products and plans.

| Example | Product | Plans | Offering |
| --- | --- | --- | --- | 
| Single product and plan | One product with a product price of $50 |  A monthly plan with a 5% discount | An offering with a monthly plan for $47.50 a month |
| Single product with multiple plans | One product with a product price of $50 | A monthly plan with a 5% discountA yearly plan with a 10% discount | An offering with two plans: A monthly plan for $47.50 a monthA yearly plan for $45 a month | 

## Building Offerings: An Overview

Here's how you build an offering:

1. Attach your repeat products. See [Repeat Products](/docs/commerce-manager/subscriptions/products/managing-products-cm).
2. Attach your plans.
    - Plans are the rules that govern your subscription, for example, any discount.
    - You can combine and reuse plans for as many products as you want, making it quick and easy to create your subscription offerings.
    - An offering must have at least one plan. See [Plans](/docs/commerce-manager/subscriptions/subscription-plans/managing-subscription-plans-cm).
3. [Create your offerings](/docs/commerce-manager/subscriptions/offerings/managing-subscription-offerings). Offerings are the products and plans that a customer can choose. An offering can consist of many combinations of products or plans, depending on the products and services you offer.
    - When a customer chooses a plan, a subscription is created.
    - Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription.

---

## What is Subscriptions?

Elastic Path Subscriptions allows you to offer your customers subscriptions and recurring billing for your products and services. Elastic Path Subscriptions gives you the flexibility to pause, update, or reactivate your subscription offerings, change subscription cycles and apply discounts.

You can create subscriptions using the [Elastic Path Subscriptions API](/docs/api/subscriptions/subscriptions-introduction) or Commerce Manager.

Scenarios include:

- repeat products that your customers purchase on a recurring basis.
- membership subscriptions where your customers pay a recurring fee to become members of a particular service, program or organization.
- subscribe and save that allows your customers to subscribe to regular deliveries of products they use frequently, for example, household essentials, or personal care items.

## How Subscriptions Work

Elastic Path Subscriptions enables you to manage your subscriptions products and plans, using offerings. Offerings can contain any combination of products and plans.

![subscription diagram](/assets/subscription_diagram.png)

Here's how a typical subscription works:

1. Create your repeat products. See [Repeat Products](/docs/commerce-manager/subscriptions/products/managing-products-cm).
2. Create your plans. Plans are the rules that govern your subscription, for example, delivery frequency, the quantity and any discount. You can combine and reuse plans for as many products as you want, making it quick and easy to create your subscription offerings. See [Plans](/docs/commerce-manager/subscriptions/subscription-plans/managing-subscription-plans-cm).
3. Create your offerings. Offerings are the product and plans that a customer can choose. An offering can consist of many combinations of a product or plans, depending on the products and services you offer. See [Offerings](/docs/commerce-manager/subscriptions/offerings/managing-subscription-offerings).

   ![subscription offering](/assets/subscription_management.png)

4. When a customer chooses a plan, a subscription is created. 
5. Elastic Path Subscriptions manages the billing and recurring payments associated with the subscription. 

## Subscriber Management

Elastic Path Subscriptions enables you to create customer accounts that you can use to manage their subscription details, including payment methods and billing information.

## Invoicing & Payments

Elastic Path Subscriptions enables you to manage the billing and recurring payments associated with your customers subscriptions. Elastic Path Subscriptions provides seamless integration with Elastic Path Payments powered by Stripe.

## Demo

<iframe class="vidyard_iframe"
  mediaType="embed"
  title="Subscriptions" src="//play.vidyard.com/zHF2XPfgFv5gtQSwo8d3mA.html?" width="640" height="360" scrolling="no" frameborder="0" allowtransparency="true" allowfullscreen referrerpolicy="no-referrer-when-downgrade"></iframe>

---

## Creating Repeat Products

The following steps describe how to create a repeat product or service in Commerce Manager.

## Prerequisites

You must create all of your currencies in your store. See [Manage Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).

## Creating a Repeat Product

The following steps describe how to create a repeat product.

:::note
Select **Product Preview** at any time to view a snapshot of your product or service.
:::

1. Log in to Commerce Manager.
2. Go to **SUBSCRIPTIONS** > **Repeat Products**.
3. Select **Create New**.
4. Enter the following information:

     | Attribute         | Required | Description                                                                                                                                                                                                                                                                                                                                                     |                                                                                            
     |-------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
     | **Name**          | Required | Enter a name for the product or service.                                                                                                                                                                                                                                                                                                                        |
     | **Description**   | Optional | The product or service description to display to customers.                                                                                                                                                                                                                                                                                                     | 
     | **SKU**           | Optional | The unique stock keeping unit of the product.                                                                                                                                                                                                                                                                                                                   |
     | **Product Image** | Optional | Products can also have rich media assets, such as images or files containing additional product details. You can either choose a file to upload or a URL that points to a file. An extensive range of [media and file extensions](/docs/commerce-manager/product-experience-manager/product-assets/files/) are supported.                                                              |
     | **Pricing**       | Required | Enter a base price of the product or service in the currency that you want to sell. This price does not include any taxes. You can configure up to ten currencies per store. See [Manage Currencies in Stores](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies). If the price includes tax, turn on the **Includes Tax** toggle. |
     | **Unit Price**    | Optional | The timeframe during which the product price is applicable, either days or months. For example, for a digital subscription, the price might be $12.99 per month.                                                                                                                                                                                                | 

5. Click **Save Product**. Your product appears in the **Subscription Products** page.
6. You can edit a product or service at any time by selecting the product you want to edit.

## Demo

<iframe class="vidyard_iframe"
  mediaType="embed"
  title="Promotions Builder" src="//play.vidyard.com/zHF2XPfgFv5gtQSwo8d3mA.html?" width="640" height="360" scrolling="no" frameborder="0" allowtransparency="true" allowfullscreen referrerpolicy="no-referrer-when-downgrade"></iframe>

---

## Creating Subscription Products in Product Experience Manager

The following steps describe how to create a repeat product or service in Product Experience Manager.

## Prerequisites

You must create all of your currencies in your store. See [Manage Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).

## Creating a Subscription Product

The following steps describe how to create a subscription product in Product Experience Manager.

:::note
When creating a product in Product Experience Manager for a subscription, you can only create new offerings. You cannot add your Product Experience Manager product to an existing offering. 
:::

1. Log in to Commerce Manager.
2. Go to **PRODUCT EXPERIENCE MANAGER** > **Products**.
3. Select **Create New**.
4. Follow the instructions described in [Creating Products](/docs/commerce-manager/product-experience-manager/products/create-products) to create your product.
5. Select the **Subscriptions** tab.
6. Select **Create New Offering**.
7. Follow the instructions described in [Creating Offerings](/docs/commerce-manager/subscriptions/offerings/creating-offerings) to create your offering.
8. You must select **Save** for your changes to take effect. If you select **Save & Exit** before selecting **Save**, your changes are lost.

    ![PXM Subscription product](/assets/subscription_pxm.png)

9. Select **Save & Exit** or **Next** depending on your requirements. 
10. You can edit a product or service at any time by selecting **...** > **Edit** on the product you want to edit.

---

## Deleting Repeat Products

You cannot delete a product that is part of an offering. You must remove a product from an offering before deleting it.

1. Log in to Commerce Manager.
2. Go to **SUBSCRIPTIONS** > **Repeat Products**.
3. Either:

    - Select **...** on a product that you want to remove, and then select **Delete**.
    - Select the checkbox on any product that you want to remove and then select **Actions** > **Delete**.

4. Select **Delete** to delete the product and close the confirmation dialog.

---

## Overview(3)

In Commerce Manager, you can create the products and services that you want to offer in a subscription. See [Creating Repeat Products](/docs/commerce-manager/subscriptions/products/creating-products).

For example, an online streaming service organization might have different services available for subscription, such as Standard Definition Streaming, High-Definition Streaming, and 4K Streaming; each service provides a specific level of video quality. Products can have additional attributes, such as price, and rich media assets, such as images or files containing additional product details. See [Product Media](/docs/commerce-manager/subscriptions/products/creating-products).

In addition, you can build offerings with products created in Product Experience Manager. Product Experience Manager manages product information, hierarchies, and price books. Ideally, Product Experience Manager becomes the single source of truth for product data across your organization. See [Creating Subscription Products in Product Experience Manager](/docs/commerce-manager/subscriptions/products/creating-pxm-products).

Product data is stored in a database. After you have added your products, you can update your product information at any time and include those products in your offerings.

## Product Media

Images and files are linked to repeat products using a hypertext reference (HREF). You can either upload your images to Commerce or you can use your own content delivery network. 

An extensive range of [media and file extensions](/docs/commerce-manager/product-experience-manager/product-assets/files) are supported.

## Product Pricing

You can assign prices for your products and services. 

In addition, you can specify a unit price for a product. A unit price is the timeframe during which the product price is applicable, either days or months. For example, for a streaming service, the price is $12.99 and the unit price is months. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many products that all have different prices. Rather than having to create separate plans for each product, you can specify the timeframe during which the product price is applicable and then create one plan that determines the billing frequency for those products.

You can display prices to your customers in their local currency. You can configure up to 10 currencies per subscription. [Create](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies) currencies only for the locales in which you do business, and select one of the currencies to be the default currency. If a default currency is not selected, the store uses the United States Dollar (USD).

In addition, when creating a plan, you can configure a total price for all the products in an offering. This is useful, as it allows you to provide a fixed price for all products in an offering, enabling those products to be offered at a discounted price. The prices you specify for a plan override the individual product prices you specified when creating a product. See [Plan Pricing](/docs/commerce-manager/subscriptions/subscription-plans/managing-subscription-plans-cm).

---

## Creating Plans

The following steps describe creating a plan.

1. Log in to Commerce Manager.
2. Go to **SUBSCRIPTIONS** > **Plans**.
3. Select **Create New**
4. (Required) Configure the plan details.

    | Option      | Required | Description                      |
    |-------------|----------|----------------------------------|
    | Name        | Required | A name for the plan.             |
    | Description | Optional | A brief description of the plan. |

5. (Required) In **Subscription Cycle**, configure the subscription cycle. The subscription cycle determines how frequently customers are charged for their subscription, and how often their subscription is renewed. For example, if you select **Years** with a timeframe of **2** your customer receives a bill annually and the subscription plan continues for 2 years. From the drop-down list select either:

    - years
    - months
    - weeks
    - days

6. (Required) Enter a timeframe.
7. (Required) In **Plan Length**, specify the duration of the subscription.
8. (Required) In **End Behavior**, select:

   - **Roll Over**: If your plan rolls over, your customers pay regularly and repeatedly.
   - **Expire**: If your plan expires, customers pay for a subscription for a specified billing cycle.

9. (Optional) In **Trial Period**, specify a trial period. For example, if your billing cycle is months, and your trial period is **1** then the trial period is 1 month.
10. (Optional) In **Plan pricing**, you can provide a price for the cost of a plan, or provide a discount on the total cost for any of the products in an offering. Alternatively, you can apply pricing directly to your products. See [Repeat Products](/docs/commerce-manager/subscriptions/products/managing-products-cm). Choose one of the following options.

     | Option     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
    |------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
     | None       | There is no price for a plan. The product price is used. See [Repeat Products](/docs/commerce-manager/subscriptions/products/managing-products-cm).                                                                                                                                                                                                                                                                                                                              |
     | Percentage | The cost of a plan equates to the total value of all products within an offering, reduced by a percentage. Enter the percentage value. For example, if you specify **10**, a 10% discount is applied to the total value of all repeat products in an offering.                                                                                                                                                                                                                   |
     | Price      | You can specify a fixed price for all the repeat products or services in an offering. This allows you to provide a fixed price for all products in an offering, enabling those products to be offered at a discounted price. Enter a price for all the currencies you have configured for your store. See [Managing Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies). If the price includes tax, turn on the **Includes Tax** toggle. | 

11. (Required) In **Rules**, decide whether to:

    - **Allow customers to pause and resume their subscription if they are using this plan**: This enables your customers to stop and restart the plan. The default is **YES**.
    - **Allow customers to cancel their Subscription if they are using this plan**: This enables your customers to permanently cancel the plan. The default is **YES**.
12. Click **Save Plan**.
13. You can edit a plan at any time by selecting **...** > **Edit** on the plan you want to edit.

## Demo

<iframe class="vidyard_iframe"
  mediaType="embed"
  title="Getting Started with Elastic Path Subscriptions" src="//play.vidyard.com/zHF2XPfgFv5gtQSwo8d3mA.html?" width="640" height="360" scrolling="no" frameborder="0" allowtransparency="true" allowfullscreen referrerpolicy="no-referrer-when-downgrade"></iframe>

---

## Deleting Plans

You must not delete a plan if it is associated with an offering as this invalidates the offering. You must detach a plan from an offering before deleting it.

1. Log in to Commerce Manager.
2. Go to **SUBSCRIPTIONS** > **Plans**. The **Subscription Plans** page displays all the plans that you have created.
3. Either:
 
    - Select **...** on the plan that you want to remove, and then select **Delete**.
    - Select the checkbox on any plans that you want to remove and then select **Actions** > **Delete**.

4. Select **Delete** to delete the plan and close the confirmation dialog.

---

## Overview(Subscription-plans)

You can use plans to model your subscription. Plans are a set of rules and conditions that manage the provision of repeat products in an offering. 

- **Subscription Cycles** - Plans specify the frequency at which your customer is billed – yearly, monthly, or weekly. See [Billing Frequency](#billing-cycles).
- **Trial Periods** - Plans specify any trial periods. See [Trial Periods](#trial-periods).
- **Recurring Payments** - Plans specify if the subscription rolls over, (customers pay regularly and repeatedly), or expired (customers pay for a subscription for a specified billing cycle). See [Recurring Payments](#recurring-payments).
- **Pricing** - Plans may also specify whether a discount is offered and specify the timeframe during which the discount is available to your customers. See [Plan Pricing](#plan-pricing).
      
You create plans based on your business requirements. Once the plans are available, you can associate the repeat products and plans in an offering. You can combine and reuse plans in your offerings. Offerings can contain any combination of products and plans. For example, your company provides customized meal boxes; you can create different subscription plans, like weekly or monthly meal boxes at specific prices. See [Creating a Plan](#creating-a-plan).

## Subscription Cycles

You can configure the subscription cycle when creating a plan. A plan's subscription cycle is determined by its subscription interval and frequency, For example, a customer with a monthly subscription set to cycle on the 2nd of the month is always billed on the second. If you do not configure a specific day or month day, then the plan is cycled from the date a subscription becomes active.

## Trial Periods
      
You can configure a trial period when creating a plan. For example, if your billing cycle is months, and your trial period is **1** then the trial period is 1 month. The trial period becomes active as soon as a subscription becomes active. When creating a subscription with a trial period, no payment method is required for the customer. An immediate invoice is still created, but with a price of zero.
      
When a trial period ends, Subscriptions automatically generates an invoice.

## Plan Pricing

You can provide a price for the total cost of a plan, or, provide a discount on the total cost of any products within an offering. For example, you can configure a percentage discount on the total cost of any products within an offering.

You can configure a total price for all the products in an offering. This is useful, as it allows you to provide a fixed price for all products in an offering, enabling these products to be offered at a discounted price. You can enter a price for all the currencies you have configured for your store. See [Managing Currencies](/docs/commerce-manager/product-experience-manager/currencies/manage-currencies).

Alternatively, instead of configuring pricing on a plan, you can set individual prices for a product when creating your products. See [Repeat Products](/docs/commerce-manager/subscriptions/products/managing-products-cm).

## Recurring Payments

There are two types of recurring payments:

- **Roll Over** - customers pay regularly and repeatedly.
- **Expire** - customers pay for a subscription for a specified billing cycle.

---

## Managing Active Subscriptions

You can view and update the active plans in subscriptions.

- Viewing the active plans for a subscription enables you to see what products and services a subscriber is paying for. This makes it easier for you to understand any immediate changes a subscriber might want, such as increasing their data limit or accessing premium features.
- Changing a subscriber's active plan means you can adapt a subscribers plan in real-time, ensuring subscriber needs are met and improving satisfaction.

## Viewing Active Subscriptions

To view all active subscriptions:

1. Log in to Commerce Manager.
2. Go to **Subscriptions** > **Subscribers**.
3. Select the subscriber whose active plans you want to view. All their subscriptions, with their current status, are displayed.

## Changing an Active Plan

You can change the active plan on a subscription:

1. Log in to Commerce Manager.
2. Go to **Subscriptions** > **Subscriptions**.
3. Select the subscription whose active plan you want to change.
4. On the plan that you want to change to, select **Actions** > **Make Active**.

---

## Managing Subscriptions

You can manage your subscribers subscriptions. You can pause, cancel and resume subscriptions. For example, a customer might pause a meal delivery service during a vacation, or want to resume a gym membership without having to start over with a new gym membership. Having a simple, straightforward process for pausing, canceling and resuming subscriptions leads to customer trust and satisfaction, which in turn improves customer retention and recovery.
      
Below is an example of what happens when pausing or canceling and resuming a subscription.
      
1. The subscriber pauses or cancels the subscription.
    - The subscription status is **Active**.
    - The subscription state is either `paused` or `canceled`, depending on the action you chose.
2. When the next billing run is due, the billing run checks the subscription state. If the subscription state is `paused` or `canceled` then no invoice is created and the subscription status is updated to `inactive`. The plan remains active until the next billing run, which is determined by your subscription cycle. For example, if your subscription cycle is 6 months and you pause the subscription after 3 months, the plan remains active until the next billing run, which will occur in 3 months.
3. Subsequent billing runs skip that subscription completely as the subscription status is `inactive`. 
4. If the subscriber resumes the subscription, when the next billing run is due, the billing run checks the subscription state. As the subscription state is no longer `paused` or `canceled`, then the billing run creates an invoice.
5. The payment run processes the invoice. Once the payment succeeds then the payment run updates the status of the subscription to `active`. 

You can either go to **Subscriptions** to pause, cancel or resume a subscription or to **Subscribers**, if you know the subscriber whose subscription you want to pause, cancel or resume. 

1. Log in to Commerce Manager.
2. Select either:

    - **Subscriptions** > **Subscribers**. A list of all subscribers is displayed.
    - **Subscriptions** > **Subscriptions**. A list of all subscriptions is displayed.
    - 

3. Either:

    - Select the subscribers whose subscriptions you want to pause, cancel and/or resume. A list of the subscribers subscriptions are displayed.
    - Select the subscriptions you want to pause, cancel and/or resume. A list of the subscriptions are displayed.

4. Select the subscription you want to pause, cancel and/or resume.
5. Select:
    - **Pause** to temporarily halt a subscription.
    - **Cancel** to permanently terminate a subscription. A cancelled subscription can be resumed.
    - **Resume** to resume a paused or cancelled subscription.

    ![cancel,pause, resume buttons](/assets/subscriptions-pause.png)

---

## Team Management

import Video from "/src/components/CardDisplay/video"

You can manage team members from the **SYSTEM > Store Settings > Team Management** tab.

## Sorting Team Members

You can sort the team member list by **Name**, **Email**, or **Role**.

## Adding Team Members

1. Select **+Invite user**.
1. In the dialog box that opens, enter a name, email address, and choose a role.

For more information, see [Inviting Team Members](/docs/commerce-manager/team-management/#adding-team-members) and [Roles](/guides/Getting-Started/team-management).

## Deleting Team Members

You can delete team members from the **SYSTEM > Store Settings > Team Management** page. This action cannot be undone.

## Changing Team Members Roles

You can change a team member’s role from the **SYSTEM > Store Settings > Team Management** page.

1. Select a team member from the table to open the **User Details** page.
1. Select the new role from the **Role** field.
1. Click the **Save** button.

:::note
The team member needs to sign in for the change to take effect.
:::

## Managing Pending Invites

On the **SYSTEM > Store Settings > Team Management** page:
- Choose **Members** to view all the members in your stores or organization.
- Choose **Pending Invites** to view all the members whom you have invited to your store or organization, but they haven't accepted the invitation. The list of pending invites displays only the Email addresses that do not belong to any users already registered in the system.

To resend or withdraw the invite, click the ellipsis associated with the **Email** and select **Resend Invite** or **Withdraw Invite**.

### Demos

<Video
  mediaSrc="https://www.youtube.com/embed/kNNRGPrqHXg"
  mediaType="embed"
  title="Understanding Roles in Commerce Manager" />

---

## Common Integration Patterns

There is much variety when it comes to building integrations. Despite that, your integrations are going to follow one of a few common patterns. Knowing what these patterns are and which ones are best suited for different scenarios will help when it comes to planning your approach to integrations – from the way to you set up your application API to how you leverage components.

Here are the common patterns we are going to examine:

- **Event-driven**: An event occurs in an app, which causes data to be sent to another app. The event may be in your system or the third-party system you are integrating with. This is probably the most common type of integration we see being used.
- **Scheduled**: An integration that runs on a regular schedule (every minute, every hour, daily, etc.) These integrations include exports (recurring reports) and imports (polling an API to request data for import to your system). Not as common as event-driven integrations.
- **Synchronous**: One system makes a request, then waits for the integration to complete and respond with an answer. Perhaps the most difficult type of integration. We don't see this one implemented very often for reasons we'll get into shortly.
- **Hybrid**: This isn't so much a pattern as parts of other patterns used together in a single integration.

Let's look at some use cases for these types and see when we should use each type and what is needed to build them.

## Event-driven integrations

As noted, this is probably the most common type of integration. When an event occurs in a source system (for example, a customer record is updated in CRM or an invoice is paid in POS), data about the event is sent to a destination system.

One of the benefits of event-driven integrations is having a near-real-time data exchange. When an event occurs in the source system, the data is sent to the destination system in seconds (or whatever time it takes to run the integration).

Event-driven integrations are further broken down into the following, which we'll get into shortly:

- One-way import
- One-way export
- Two-way

### Webhooks and payloads

We've touched on events, but we also need to cover webhooks and payloads. A **webhook** is an event-triggered request to an app. This is the third-party app, for an import integration, or your app, for an export integration. The **payload** is the data sent by the webhook.

While we commonly use the term webhook, some companies use different terms. For example, Salesforce refers to these as [Outbound Messages](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_om_outboundmessaging_understanding.htm), and Slack calls them [Events](https://api.slack.com/apis/connections/events-api).

The bottom line is that _something_ changes in the source system, which causes the source system to send data outside the system.

:::note
When the destination system creates an endpoint, it tells the source system, *when thing changes, let me know at this URL.*. That is, it is limited to defining where the payload is sent.
:::

For example, you could set up a webhook in an inventory app to notify you when the quantity for an inventory item is updated. When an update occurs in the inventory system, the system might send an HTTP request with a payload like this:

```json
{
  "event": "INVENTORY_UPDATE",
  "updates": [
    {
      "item": "widgets",
      "action": "add",
      "quantity": 20
    },
    {
      "item": "gadgets",
      "action": "remove",
      "quantity": 5
    }
  ]
}
```

For a great example of an event-driven API, let's consider GitHub, which has a variety of events that can trigger a webhook. GitHub also provides the shape of the payload sent via each webhook: [https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads).

When you integrate with GitHub, you'll create endpoints to receive those payloads: [https://docs.github.com/en/rest/repos/webhooks?apiVersion=2022-11-28](https://docs.github.com/en/rest/repos/webhooks?apiVersion=2022-11-28).

### Pub/sub systems

Though webhooks are perhaps the most common type of a pub/sub (publisher/subscriber) system, the source system for an integration may also be using Amazon SNS, Apache Kafka, email, or something else altogether. In each case, these systems provide you with something you subscribe to as the starting point for the integration.

### One-way import integration

Now that we've covered event-driven integrations in general, let's dive into the details of a (relatively) simple one-way event-driven import. This is an import of data from the third-party app into your app based on events in the third-party app. Once you've built a couple of these imports, you should be able to put the next one together pretty quickly and with a minimum of components.

#### Multiple events

First, let's talk about importing data from a third-party app that supports webhooks (or another pub/sub system). You may initially be importing a single, simple payload and may want to subscribe to only what you immediately need from the third-party system. However, you should probably subscribe to several webhooks (if available) in the third-party app to support the different payloads you may eventually need to receive.

After all, an import integration does not need to be limited to a single type of data or payload. A single integration, for example, may allow you to get updated customer records from a third-party system and updated order records from the same system. These different datasets may all be provided to your app via the same integration, but they may be sent via multiple webhooks in the third-party app.

#### Branching and flows

To support different events in the third-party app, you can either use branching or set up a unique flow within the integration for each event type. If your integration handles a small number of webhook events, then branching may be the best option. If, however, the integration is more complex, with substantially different logic for each payload, it is better to use [flows](/docs/composer/builder/best-practices/tap-into-power-flows).

For an example of flows to support multiple events, let's consider Salesforce. You might have one flow in your integration that supports the Opportunity update event, with separate flows for the Opportunity create event and the Contact create event. By setting things up this way, each flow handles a small piece of the overall integration, and code used in separate flows is tailored precisely to the payload the flow is processing.

If the third-party app supports it, you could create a separate webhook for each flow. You could then use a [pre-process flow](/docs/composer/builder/integrations/integrations-triggers/endpoint-configuration#instance-specific-endpoint-with-a-preprocess-flow) with a single endpoint. A pre-process flow examines incoming payloads and dispatches them appropriately to the integration's other flows.

#### Deploy-time flow

[A deploy-time flow](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#instance-deploy-trigger) helps to ensure that the webhooks are set up accurately. Deploy-time flows are set to run when you (or one of your customers) activate the integration. Since a deploy-time flow knows the webhook URLs (endpoints) for all its sibling flows, it can define those endpoints for the third-party app. This ensures that payloads are sent to the correct endpoints.

#### Third-party app component for import

If you are integrating with a common app for which we already have a component, you shouldn't need to write any custom code.

You might also have a scenario where the third-party app returns a subset of needed data (maybe IDs of records that have changed but not the actual records themselves). In this scenario, you may need to wrap a bit of the third-party API with your integration to get the records associated with the IDs before sending the entire payload to the next step in the integration.

### One-way export integration

Now that we've looked at the one-way event-driven import integration, let's flip everything around and look at the reverse. The primary difference between an export integration and an import integration is that the export integration starts with your core application, giving you absolute control over the initial steps of the integration.

#### Your app

You'll want to write the core product functionality for the export one time, so you don't have to keep building additional functionality. The best approach is to set up your app with an API that includes events, webhooks, and the corresponding payload definitions. Doing this saves considerable time for your developers since they won't need to keep defining new export functionality for the API. Instead, you can create integrations that subscribe to your webhooks, filter/transform the resulting payloads, and send the data to the third-party app.

If your app does not have an API, you'll probably need to use [scheduled integrations](#scheduled-integrations) instead of event-driven ones.

#### Third-party app component for export

If a standard component is available to access the third-party API, you will want to use that. If one isn't available, we recommend using the HTTP component to make calls to the third-party API or contact Elastic Path to have a standard component created. 

### Two-way event-driven integration

A two-way event-driven integration melds the one-way event-driven export and the one-way event-driven import into a single integration. The import will have its own flow or [flows](/docs/composer/builder/best-practices/tap-into-power-flows), and the export will have its own flow or flows, but everything is contained within a single integration. A two-way integration most likely uses API calls for your app but a built-in component for the third-party app (since this is both an import and export integration). The advantage being you will have a single integration to support.

We recommend doing this as a single integration using multiple flows instead of assembling the pieces into several one-way integrations. Building a single integration simplifies integration development, deployment, and support.

## Scheduled integrations

When the system you need to transfer data from does not have webhooks or another pub/sub system to which you can subscribe, you need to use a scheduled integration. A scheduled integration can be either import or export. Instead of being triggered when the integration receives a notification, a scheduled integration is triggered at a specific time or time interval. For example, a scheduled integration may run every two minutes or every Thursday at 7:00 PM.

By definition, a scheduled integration is not near-real-time. For a scheduled integration that recurs frequently, the data may be only a minute or two old, but it will not be as fresh as one can get from an event-driven integration.

The main difference between a scheduled integration and an event-driven one is that the source system in an event-driven integration says, "I have something," but a scheduled integration asks the source system, "What do you have for me?"

Scheduled integrations generally fall into one of the following:

- Scheduled data import
- Scheduled file import
- Scheduled file export

### Scheduled data import integration

You'll use a scheduled integration to import when you have a third-party API that does not have webhooks or another pub/sub system. If a pre-built component is available, then you will use that. If a pre-built component for this third-party app isn't available, you'll need to build a fully fleshed-out integration that wraps the various API endpoints containing the data the integration will query. The API then processes the query and returns the requested payload.

### Scheduled file import integrations

Some third-party apps may be configured with a file export instead of an API, which is more common with non-SaaS (legacy) systems. In this case, the app may write out data as PDF, XML, CSV, or another file type to an external data source such as Dropbox, SFTP, MS SQL, Queue, and so on. To import this data, you'll build an integration that checks the location(s) according to a regular schedule to see if there are new files to process.

When there is new data within the location (for example, new XML files in a Dropbox folder), your integration will loop over each of the files, process the files, and then move or delete the processed files. As with other scheduled integrations, this still is not near-real-time but can be current within a few minutes of the file(s) being placed in the external data source.

### Scheduled file export integration

We tend to see this type of integration where you generate a regular report for your customers. You set up an integration where you are either querying your API (for your app) or a third-party API for specific data.

Once the data has been returned, your integration generates a file with the data in the necessary format (PDF, XML, CSV, and so on.) Finally, this file is packaged up and sent off to its destination (which could range from a filesystem to email or SMS).

You should be able to use a built-in Builder component to handle the part where the file is placed into a filesystem, sent via email, etc.

Some of the common data platforms for which builder has built-in components are Dropbox, Amazon S3, Google Drive, and Azure Files.

## Synchronous Integrations

A synchronous integration may be what you need if you have data from a third-party app that you must have *right* now. An integration of this type calls an integration URL and then waits for a response.

If a synchronous integration is working quickly and has very little to no lag between the call and the response, then the integration should work well. However, if the integration takes a while to run (much data to process, the third-party app is slow in fulfilling requests, etc.), that makes the integration susceptible to network disconnects and timeouts.

You are probably better off building this as a two-way asynchronous integration. Then, the integration can send off the request and "hang up." When the integration completes the process, it can "redial" to return the requested data.

## Hybrid Integrations

As noted, hybrid integrations are some combination of other integration types. For example, suppose that your app supports webhooks, but the third-party app you are working with only has an API with no webhooks. As a result, you might build a hybrid integration where you have an event-driven export from your app but are running a scheduled data import from the third-party app. Instead of setting this up as two separate integrations, you would be able to combine them in the same integration with distinct flows.

---

## Create Webhooks in Your Core Product

Webhooks in your core app allow you to simplify export integrations. Setting up webhooks may add quite a bit of development time to the first export integration, but subsequent integrations can be completed much faster because of the webhooks. And, speaking of faster, webhooks help your export work in near-real-time.

Webhooks are also not limited in terms of endpoints, so they can be used to export data to multiple destinations. For example, if you have a webhook that [triggers](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#webhook-triggers) whenever there is an update in your inventory system, and it fires off a payload that includes updated inventory data (even if some of that data is extraneous to the current integration), you can easily filter that data within the integration to what is needed by the destination system. Then, when you are creating the next integration for inventory updates, you already have the payload with everything in it (which you can now filter for a different dataset for your second integration).

Once you have webhooks set up for your core app, you shouldn't need nearly as much help from devs to build out additional export integrations. In fact, your technical non-developers should be able to build export integrations that follow the same pattern as existing integrations. This frees your devs to work on the core product rather than the integrations.

---

## Drive Integrations with Config Variables

Builder allows you to build productized, reusable integrations that can be configured differently for each consumer. In addition, you can set specific config variables for your instances to use, and you can restrict other variables to your integration development teams.

## What are config variables?

A config variable is a value that can be different for each of your consumers of a given integration. The key here is that the value _can_ be different for each consumer but does not _need_ to be different. You may have a variable that 95% of your consumers don't change from the default, but 5% need it to be something else. You'll still want to set it up as a config variable instead of hardcoding it.

Items frequently defined as config variables include auth info, API endpoints, Slack channels, file paths, and data mappings. This is not an exhaustive list but should give you an idea of the breadth of possibilities for config variables.

## What types of variables should you use?

We support a variety of config types, ranging from a simple string to multi-field connection variables. A full list of the config types is found in our [Building Integrations](/docs/composer/builder/integrations/building-integrations#config-variable-data-types) article.

## What should you set as a config variable?

There are a surprising number of things that should become config variables. We've categorized them as follows:

### Anything that might change on a consumer basis

Before building an integration, try to think through absolutely everything that can change from one consumer to another. Even if there is a value that is currently the same for each existing consumer, but the value could change in the future, set that up as a config variable. You can always set the value your consumers are currently using as the default value.

## Anything used as an input in multiple places

Suppose you have a file path that you use as an input for each of ten SFTP steps. You'll want to make that file path a variable, so when you inevitably need to change it, you can do so in one place instead of editing ten different steps. This is one of the scenarios where you'll want to set the value for the config variable but only show it to your integration development teams.

## Anything that changes between environments

Suppose you have an endpoint (`https://prod.example.com/api`) that all your consumers use. However, your team needs to use another endpoint (`https://qa.example.com/api`) for testing. You'll want to define “endpoint” as a config variable, set the default to “prod,” and make it “not customer configurable.” Then, your instances won't see that it is a variable and can't inadvertently change it and break the integration. But your team can easily toggle the value as needed.

## How do you make the configuration wizard easy for consumers?

When your consumers activate an instance, they are taken to the configuration page. To ensure that your consumers have the best possible activation experience, you want to make the page as straightforward to use as possible. The goal is for consumers to click a few toggles and dropdowns, maybe type a string or two, and they are good to go.

Here are a few things you can do to help your consumers with config variables:

### Use headings

Let's say that you've built an integration that connects to Salesforce and Dropbox. Create a heading on the config page that says “Dropbox” and place the connection and file path variables under that heading. Then, create another heading for “Salesforce” and place the connection and other variables under that heading. Here's an example of using [headings for config variables](/docs/composer/builder/quickstarts/integrations/configuration-driven-integration#basic-config-variables).

### Use descriptions

Give each config variable a description. These show up in the instance activation page as helpful text located below each config variable. It is especially beneficial if the descriptions include examples (where the config variable is something other than a button, toggle, or dropdown). For example, if the instance needs a Slack webhook URL, you can make sure the description text says something like, “Your URL should look like this: `https://hooks.slack.com/some/api/key`.”

### Use default values

We've already touched on this a bit, but using default values can simplify the activation process greatly. If you know that consumers will generally use a specific value (though not always, or perhaps not always in the future), set that as the default value for the config variable.

### Use dropdown menus

If it makes sense to use a dropdown menu for config variables, please do so. This allows users to select valid options but limits their ability to break the instance by entering invalid data.

---

## Retry and Replay Save Time

Not all systems are accessible all the time. So, when it makes sense, you should [build a retry function](/docs/composer/builder/integrations/building-integrations#integration-retry-configuration) into an integration. Retry allows the system to automatically resend the payload to the destination system every few minutes or even according to a geometric progression (retry in 2 minutes, 4 minutes after that, 8 minutes after that, etc.) Setting the retry in the integration ensures that your integration is still likely to run successfully if the destination system or something in the integration suffers a temporary outage.

Using the retry function also ensures that you are not getting your devs involved with solving an integration issue until you have determined that the problem is more severe than a brief system outage. Including the retry function in integrations prevents many transient issues from being brought to support.

If, however, the error persists (for example, the destination system appears to be up, but the integration keeps throwing some type of internal server error message), you may need to move up from the retry function to the replay function.

Unlike retry, replay is not something that can be done automatically within an integration. Instead, it is a function you manually invoke by clicking the replay button in the UI for that instance. Doing this runs the full integration with the same payload as before while allowing you to debug by viewing all the steps in the integration as they execute to determine precisely what is working and where things error out.

---

## Secure Webhook Endpoints with HMAC

When it comes to transferring data via integrations, security is a top concern. To secure data being passed via webhooks [for event-driven integrations](/docs/composer/builder/best-practices/common-integration-patterns#event-driven-integrations), you have a few options, including API keys, your own authorization headers, or HMAC. 

We recommends using HMAC because it's about the the simplest (and stoutest) approach you could use. It doesn't require that your team learn a new language or gain an advanced understanding of encryption, but it does an excellent job of protecting the integrity of your data at the point of transfer.

## What is HMAC?

HMAC, or hashed message authentication code, is an authentication method that generates a hash from a message and a cryptographic key. When you implement HMAC for your webhook, you'll use an algorithm such as MD5, SHA-256, or RipeMD-128 for the hash to ensure the HTTP request that shows up at your webhook endpoint is legit.

## How does HMAC work?

Before the source app sends an HTTP request via the webhook, it hashes the payload (request body) with HMAC using the secret key. The resulting hash is then bundled into the HTTP request as a header, and the entire request (header and body) is sent to the webhook endpoint.

Upon receiving the HTTP request, the destination app hashes the body with the secret key and then compares the result to the hash provided in the header. If the values match, the destination app knows the data is legit and processes it. If the values do not match, the destination app rejects the data and executes whatever code was written for that scenario — perhaps creating a log entry or sending a notification.

If someone tries to spoof the payload, they won't be able to generate a valid hash since they don't have the secret key. Door closed.

## HMAC language support

Here are a few links to popular languages with HMAC capabilities:

- [NodeJS](https://nodejs.org/api/crypto.html)
- [Python](https://docs.python.org/3/library/hmac.html)
- [PHP](https://www.php.net/manual/en/function.hash-hmac.php)
- [.NET C#](https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.hmac?view=net-6.0)

## Example code for HMAC

Here is an example of how HMAC might be set up in NodeJS using the built-in crypto module:

```tsx
const crypto = require("crypto");

const SECRET_KEY = "secret-FA782CF7-060E-484E-B3DC-055CF2C9ED99";

const payload = JSON.stringify({
  event: "REFUND_REQUEST",
  user: "realcustomer@mail.com",
  amount: "50.25",
});

const hash = crypto
  .createHmac("sha256", SECRET_KEY)
  .update(payload, "utf-8")
  .digest("hex");

console.log(hash); // Prints d12f95e3f98240cff00b2743160455fdf70cb8d431db2981a9af8414fc4ad5f8
```

The corresponding HTTP request using HMAC might look like this:

```bash
curl https://my.webhook.endpoint.com/callback \
	--request POST \
	--header "x-hmac-hash: d12f95e3f98240cff00b2743160455fdf70cb8d431db2981a9af8414fc4ad5f8" \
	--data '{"event":"REFUND_REQUEST","user":"realcustomer@notabaddie.com","amount":"50.25"}'
```

## Further resources

Setting up a HMAC for one of your integrations should be straightforward. To make things even simpler, we've added an HMAC Webhook trigger to our built in Hash component.

---

## Tap Into the Power of Flows

A single integration can have a [single flow](/docs/composer/builder/integrations/building-integrations#flows-in-integrations) (for the simplest integrations). However, many integrations benefit from having [multiple flows](/docs/composer/builder/quickstarts/integrations/building-an-integration-with-multiple-flows). For example, a two-way integration has both import and export flows.

Using different flows within a single integration allows each flow to have its own endpoints, triggers, and steps. You can even mix and match types within an integration where some flows run on schedules, some are based on webhooks, and others run automatically upon deployment/activation.

Instances (an integration deployed for a single consumer) can have common endpoints, or you can configure the system with a separate endpoint for each instance. Similarly, flows can have a common endpoint, or they can each have a different one. It's common practice to use pre-process flows to route data to the correct flow.

Using multiple flows in a single integration, instead of building a separate integration for each flow, also means that consumers only need to activate a single integration within the [Integrations Hub](/docs/composer/integration-hub/integrations-hub).

---

## Version Your Integrations

In a perfect world, you wouldn't need to version anything for integrations. Your team would get it right the first time they build an integration and no one would ever change anything. Unfortunately, none of us live in a perfect world. Fortunately, we have a good solution for managing component and integration versions.

We have largely built best-practices for versioning into the platform, to ensure that it is easy for your to determine what versions of components and integrations are available but also to know which ones are currently deployed. In addition, there are some steps you can take to make best use of the versioning functionality and we call those out in the following sections.

## How integrations are versioned?

Integrations can be versioned. When you've created/modified and then tested an integration and you click "Save & Publish," the system increments the version by 1. An original integration will have V1, followed by V2, etc.

![Integration designer with integration version](/assets/integration-version.png)

Versioning an integration does not automatically deploy that version to consumers of the integration. Automatic deployment could be very bad, since a change to an integration for one consumer might break something for another. Not all consumers may be on the newest version of your integration; some may be using a legacy version of a third-party service which requires them to stay on their current integration version.

Instead, your integration development team decides who gets which version and when — with no need to rely on dev or DevOps to make the updates. Team members can simply select the desired integration version from the available list in the Config Wizard, enter any needed configuration data and click "Next" or "Finish."

![Integration designer with instance version](/assets/instance-version.png)

If something should go wrong when you switch a customer to a new version of the integration, you can easily revert to the prior version of the integration by following a similar process. Simply click "Reconfigure," select the correct version of the integration, and click "Save and Deploy" once again. 

### What can you do with integration versioning?

Each time you publish a version, you can include a comment (basically a commit message) summarizing the changes.

Ideally (to make maintenance sane), you'll want to keep consumers on newer versions of integrations. To support that, you can mark any version of an integration as deprecated (using the integrations Version History drawer). Once a version is deprecated, it will still show in the list, but will not be selectable by your team for deployment/activation.

If you know for certain that you want all your consumers to be updated to the current version, you can click "Update all Instances" in the version drawer.

Only one version of a given integration can be made available in the [Integrations Hub](/docs/composer/integration-hub/integrations-hub), but that's not automatically updated (since nothing is automatically updated) when a new version is created. You can have your team deploy a new version of an integration internally for testing, but only allow your consumers to update their instances via the marketplace when that QA is complete.

---

## Advanced Commerce Component

You can integrate Commerce with Advanced Commerce (GrapheneHC) using the Advanced Commerce component. This means you can synchronize Commerce data such as products, prices, images, categories, custom attributes, and variations with your Advanced Commerce (GrapheneHC) storefront, giving you advanced searching and merchandising capabilities. The component allows you to create, delete and update products in Advanced Commerce.

## Connections

You need the following to interact with Advanced Commerce (GrapheneHC).

| Option            | Description                                   |
|:------------------|:----------------------------------------------|
| **API Base URL**  | Your Advanced Commerce API Base URL, for example, `https//{{domainKey}}.api-{{location}}.advancedcommerce.services`. Contact your Advanced Commerce team. |
| **API Key** | Your Advanced Commerce API Key.  |
| **API Secret** | Your Advanced Commerce Secret.  |

## Actions

The component has the following actions.

### Process Upload

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Advanced Commerce Connection. | 
| **Receipt Id** | `string` | A unique identifier of a receipt. | 
| **Delete On Completion** | `boolean` | Specifies whether to delete on completion. | 

### Upload File

| Input | Type | Description | 
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Advanced Commerce Connection. | 
| **Zip File Path** | `string` | The path to a zip file. | 
| **Type** | `string` | The file type. | 

### Write File

| Input | Type | Description | 
|:--- |:--- | :--- | 
| **File Path** | `string` | A file path. | 
| **Content** | `dynamicfieldselection` | The file contents. | 

### Zip File

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Files to be zipped Inputs** | `string` | A list of files to be zipped. |
| **Zip File Path** | `string` | A file path. |

---

## Algolia Component

You can integrate Commerce with Algolia using the Algolia component. This means you can synchronize Commerce data such as products, prices, images, categories, custom attributes, and variations with Algolia, giving you advanced searching capabilities. 

## Connections

You can find this information in the **Settings, Teams and Access, API keys** section on the Algolia Dashboard.

| Option            | Description                                   |
|:------------------|:----------------------------------------------|
| **App ID**        | Your Application ID for your Algolia account. |
| **Admin API key** | Your Admin API Key for your Algolia account.  |

## Actions

The component has the following actions.

### Copy Index

| Input | Type | Description | 
|:--- |:--- | :--- | 
| **Application ID** | `string` | Your Application ID for your Algolia account. | 
| **Admin  API Key**  | `string` | Your Admin API Key for your Algolia account. | 
| **Source** | `string` | The sources from which to get the items to display. | 
| **Target** | `string` | The target Algolia index. | 
| **Scopes Inputs** | `string` | The scope, for example, exclude or include some users and groups, limit duration of a user's access and so on.  | 

### Copy Settings

| Input | Type | Description | 
|:--- |:--- | :--- | 
| **Application ID** | `string` | Your Application ID for your Algolia account. | 
| **Admin  API Key**  | `string` | Your Admin API Key for your Algolia account. | 
| **Source** | `string` | The sources from which to get the items to display. | 
| **Target** | `string` | The target Algolia index. | 

### Get Indices Details

| Input | Type | Description | 
|:--- |:--- | :--- | 
| **Application ID** | `string` | Your Application ID for your Algolia account. | 
| **Admin  API Key**  | `string` | Your Admin API Key for your Algolia account. | 
| **Index Name** | `string` | Your Algolia index name. | 

### Move Index

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Application ID** | `string` | Your Application ID for your Algolia account. | 
| **Admin  API Key**  | `string` | Your Admin API Key for your Algolia account. | 
| **Source** | `string` | The sources from which to get the items to display. | 
| **Target** | `string` | The target Algolia index. | 

### Multi-batch Add/Update

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Application ID** | `string` | Your Application ID for your Algolia account. | 
| **Admin  API Key**  | `string` | Your Admin API Key for your Algolia account. | 
| **Batch Object** | `string` | The objects to add/update. |

### Replace All Objects

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Application ID** | `string` | Your Application ID for your Algolia account. | 
| **Admin  API Key**  | `string` | Your Admin API Key for your Algolia account. | 
| **Source** | `string` | The sources from which to get the items to display. | 
| **Target** | `string` | The target Algolia index. |  
| **Objects Inputs** | `string` | The objects to replace. |

---

## Amazon Cognito Component

You can integrate Commerce with Amazon Cognito, This allows you to offer your customers or business users Single Sign-on (SSO) using Amazon Cognito credentials instead of Commerce credentials. When you create an Amazon Cognito integration, an Amazon Cognito user pool is created. Your customers can then sign-in directly using the user pool.

## Connections

Collect the following Amazon credentials. See [Create an AWS access key](https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/).

| Amazon Cognito Connection | Description                 |
|:-----------------------|:----------------------------|
| **Access Key ID**      | Your AWS Access Key ID.     |
| **Secret Access Key**  | Your AWS Secret Access Key. |

## Actions

The component has the following actions.

### Create User Pool

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | AWS connection. |
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool Request**  | `code` |  The API request to create a user pool. See [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html). |

### Create User Pool Client

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. | 
| **AWS Cognito User Pool Request**  | `code` |  The API request to create your user pool client. See [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html). |

### Create User Pool Domain

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool Request**  | `code` |  The API request to create a user pool. See [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html). |
| **Domain Name**  | `string` |  The domain name you want to use for your user pool. It must be unique. We recommend that your domain name is alphanumeric and you only use the `-` special character. The domain is in the format of `https://*<domain_prefix>*.auth.<*region*>.amazoncognito.com`. For example, if your domain name is `elasticpath-commerce-cloud` and your AWS region is `us-east-1` then your login URL is `elastic-path-commerce-cloud.auth.us-east-1.amazoncognito.com`. The Amazon Cognito Integration creates a subdomain within an Amazon Cognito domain. If you want to use your business domain, then you must configure this directly in Amazon Cognito. | `elastic-path-commerce-cloud.auth.us-east-1.amazoncognito.com` |
| **Custom Domain Certificate ARN**  | `string` | The SSL certificate for your custom domain. You can use Amazon Cognito to change the certificate that you applied to your custom domain. Usually, this is unnecessary following routine certificate renewal with ACM. When you renew your existing certificate in ACM, the ARN for your certificate remains the same, and your custom domain uses the new certificate automatically. However, if you replace your existing certificate with a new one, ACM gives the new certificate a new ARN. To apply the new certificate to your custom domain, you must provide this ARN to Amazon Cognito. | 

### Delete User Pool Domain

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool ID**  | `string` |  The ID of your user pool. |  
| **Domain Name**  | `string` |  The domain name you want to use for your user pool. It must be unique. We recommend that your domain name is alphanumeric and you only use the `-` special character. The domain is in the format of `https://*<domain_prefix>*.auth.<*region*>.amazoncognito.com`. For example, if your domain name is `elasticpath-commerce-cloud` and your AWS region is `us-east-1` then your login URL is `elastic-path-commerce-cloud.auth.us-east-1.amazoncognito.com`. The Amazon Cognito Integration creates a subdomain within an Amazon Cognito domain. If you want to use your business domain, then you must configure this directly in Amazon Cognito. |

### Describe User Pool

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool ID**  | `string` |  The ID of your user pool. | 
| **Domain Name**  | `string` |  The domain name you want to use for your user pool. It must be unique. We recommend that your domain name is alphanumeric and you only use the `-` special character. The domain is in the format of `https://*<domain_prefix>*.auth.<*region*>.amazoncognito.com`. For example, if your domain name is `elasticpath-commerce-cloud` and your AWS region is `us-east-1` then your login URL is `elastic-path-commerce-cloud.auth.us-east-1.amazoncognito.com`. The Amazon Cognito Integration creates a subdomain within an Amazon Cognito domain. If you want to use your business domain, then you must configure this directly in Amazon Cognito. | 

### Describe User Pool Client

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool ID**  | `string` |  The ID of your user pool. |
| **AWS Cognito User Pool Client ID**  | `string` |  The ID of your client user pool. |

### Describe User Pool Domain

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **Domain Name**  | `string` |  The domain name you want to use for your user pool. It must be unique. We recommend that your domain name is alphanumeric and you only use the `-` special character. The domain is in the format of `https://*<domain_prefix>*.auth.<*region*>.amazoncognito.com`. For example, if your domain name is `elasticpath-commerce-cloud` and your AWS region is `us-east-1` then your login URL is `elastic-path-commerce-cloud.auth.us-east-1.amazoncognito.com`. The Amazon Cognito Integration creates a subdomain within an Amazon Cognito domain. If you want to use your business domain, then you must configure this directly in Amazon Cognito. | 

### List User Pool

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **Max Result**  | `string` |  The maximum results. |  

### Describe User Pool Client

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool ID**  | `string` |  The ID of your user pool. |  

### Update User Pool

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool Request**  | `code` |  The API request to update your user pool. See [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html). |

### Update User Pool Client

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool Client Request**  | `code` |  The API request to update your user pool client. See [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html). | 

### Update User Pool Domain

| Input | Type | Description |
|:--- |:--- | :--- | 
| **AWS Region** | `string` | AWS provides services in multiple regions, like `us-west-2` or `eu-east-1`. AWS region indicates the region in which your buckets are stored. |
| **AWS Cognito User Pool Request**  | `code` |  The API request to update your user pool. See [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html). |
| **Domain Name**  | `string` |  The domain name you want to use for your user pool. It must be unique. We recommend that your domain name is alphanumeric and you only use the `-` special character. The domain is in the format of `https://*<domain_prefix>*.auth.<*region*>.amazoncognito.com`. For example, if your domain name is `elasticpath-commerce-cloud` and your AWS region is `us-east-1` then your login URL is `elastic-path-commerce-cloud.auth.us-east-1.amazoncognito.com`. The Amazon Cognito Integration creates a subdomain within an Amazon Cognito domain. If you want to use your business domain, then you must configure this directly in Amazon Cognito. | `elastic-path-commerce-cloud.auth.us-east-1.amazoncognito.com` |
| **Custom Domain Certificate ARN**  | `string` |  The SSL certificate for your custom domain. You can use Amazon Cognito to change the certificate that you applied to your custom domain. Usually, this is unnecessary following routine certificate renewal with ACM. When you renew your existing certificate in ACM, the ARN for your certificate remains the same, and your custom domain uses the new certificate automatically. However, if you replace your existing certificate with a new one, ACM gives the new certificate a new ARN. To apply the new certificate to your custom domain, you must provide this ARN to Amazon Cognito. |

---

## Avalara Component

You can quickly and easily integrate Commerce with Avalara using the Avalara component. The Avalara component enables you to commit tax and void tax on specific order events. 

## Connections

You need the following to interact with Avalara.

| Option            | Description                                   |
|:------------------|:----------------------------------------------|
| **Company Code**        | Your company code. |
| **Avalara API Version** | Your API version.  |
| **Avalara Environment** | Your Avalara environment. |
| **Avalara Username** | Your Avalara username.  |
| **Avalara Password** | Your Avalara password.  |

## Actions

The component has the following actions.

### Commit the transaction in Avalara

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection`  | Your Avalara connection. | 
| **Commit transaction Order payload Request**  | `string` | The payload delivered to your webhook from Commerce contains the information about the resources affected by the fired event. | 
| **Log Level** | `string` | The level of logging. | 

### Void the transaction in Avalara

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Your Avalara connection. | 
| **Void transaction Order payload Request**  | `dynamicfieldselection` | The payload delivered to your webhook from Commerce contains the information about the resources affected by the fired event. | 
| **Void Reason Code** | `string` | The void reason code. | 
| **Log Level** | `string` | The level of logging. |

---

## Catalog Publish Component

You can use the Commerce Catalog Publish component to use Commerce catalogs in third-party integrations, like Algolia. 

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Actions

The component has the following actions.

### Get all Catalogs

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Log Level** | `string` | The level of logging. | 

### Get the Catalog Release Status

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Catalog ID** | `string` | The unique identifier for the catalog. | 
| **Release ID** | `string` | A unique identifier for the catalog release. | 
| **Log Level** | `string` | The level of logging. | 

### Publish Catalog

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Catalog ID** | `string`  | The unique identifier for the catalog. | 
| **Log Level** | `string` | The level of logging. | 

### Process Configuration and Prioritize Catalogs

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Config JSON** | `string` | The configured JSON. | 
| **Log Level** | `string` | The level of logging. |

---

## Elastic Path Commerce Cloud Component

You can use the Elastic Path Commerce Cloud component to perform tasks within Elastic Path Commerce Cloud, for example, publish catalogs, import products, assign products to nodes and so on.

## Connections

Collect the following Elastic Path Commerce Cloud API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Elastic Path Commerce Cloud API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Elastic Path Commerce Cloud API Base URL. |
| **Client ID**                       | Your Elastic Path Commerce Cloud Client ID. |
| **Client Secret**                   | Your Elastic Path Commerce Cloud Client Secret. |

## Triggers

### Elastic Path Commerce Cloud Webhook

A webhook trigger to consume HTTP webhooks from Elastic Path Commerce Cloud. Supports authentication via the webhook `Secret Key` which is passed to webhooks within the `X-MOLTIN-SECRET-KEY` HTTP header.

| Input | Description                            |
|:------------------------------------|:---------------------------------------|
| **Webhook Secret Key** | **Optional** The API secret used to authenticate calls to the webhook. A default value is provided that is randomly generated by the NodeJS crypto library. If **Webhook Secret Config** is provided, this field is ignored. |
| **Webhook Secret Config** | **Optional** A JSON object used to configure the webhook secret. Must contain a `webhookSecretKey` field with the secret value (e.g., `{"webhookSecretKey": "your-secret"}`). Use this input with a JSON Forms integration configuration variable to securely supply the secret without exposing it directly. |
| **Response Type** | Select `Synchronous` if the webhook response must be sent back to Elastic Path Commerce Cloud.  Select `Asynchronous` if the webhook must send an immediate response to Elastic Path Commerce Cloud containing the execution ID before processing the event. |
| **Error Handler Type** | Select the preferred behavior for error handling. |
| **Retry** | Select if the flow must be automatically retried if an error is returned. Only applies if the `Response Type` is `Asynchronous`. |
| **Retry Attempts** | Specify the maximum number of times the request must be processed if errors are returned. Only applies if the `Response Type` is `Asynchronous`. |
| **Minutes Between Attempts** | Specify how many minutes to wait between retries. Only applies if the `Response Type` is `Asynchronous`. |
| **Exponential Backoff** | Wait twice as long between each retry. Only applies if the `Response Type` is `Asynchronous`. |
| **Retry Cancellation** | Report or ignore the error if the final retry fails. Only applies if the `Response Type` is `Asynchronous`. |

## Actions

The component has the following actions.

### Allocate Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. | 
| **Quantity** | `string` | The amount of the product to allocate. | 
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Cancel Transaction

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Order ID** | `string` | The unique identifier of the order. |
| **Transaction ID** | `string` | The unique identifier of the transaction. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Capture Transaction

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Order ID** | `string` | The unique identifier of the order. |
| **Transaction ID** | `string` | The unique identifier of the transaction. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Refund Transaction

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Composable Commerce connection. |
| **Order ID** | `string` | The unique identifier of the order. |
| **Transaction ID** | `string` | The unique identifier of the transaction. |
| **Amount** | `string` | The amount value to be refunded. |
| **Override Token** | `string` | The output of `Generate Override Token` action to be used with organizations. |

### Create a Field

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **name** | `string` | The name of the field. |
| **slug** | `string` | A unique slug identifier for the field. |
| **field_type** | `string` | This field is immutable and cannot be updated. Types of fields are: `string`, `integer`, `boolean`, `float`, `date`, or `relationship`. |
| **description** | `string` | Any description for this field. |
| **required** | `boolean` | `true` if required on input, `false` if not. Always `false` if the `field_type` is a relationship. |
| **enabled** | `boolean` | If this field is enabled on the flow this must be `true`, otherwise `false`. |
| **flow_id** | `string` | The unique identifier of the flow that the field belongs to.  |
| **default** | `string` | A default value if none is supplied and field is not required. |
| **order** | `string` | Denotes the order in which this field is returned relative to the rest of the flow fields. |
| **omit_null** | `boolean` | Hide this field from responses if the value is `null`. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create a File (By Location)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **File Location** | `string` | Location of the file. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create a Pricebook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Name** | `string` | The name of the price book. |
| **Description** | `string` | The purpose for the price book, such as flash sale pricing or preferred customer pricing. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create a Price in a Pricebook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Pricebook ID** | `string` | The unique identifier of the pricebook. |
| **SKU** | `string` | The product SKU that the prices belongs to. |
| **Currencies** | `string` | A collection of one or more currencies. |
| **Sales** | `string` | A collection of one or more sales. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create Account 

| Input | Type |  Description |
| --- | --- | --- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` |  The output of Generate Override Token action to be used with Organizations. |
| **Account Request** | `string` | The API request to create an account. Avoid using `data` parameter in the request. |

For **Account Request**, see the following snippet:

```json
  {
    "type": "account",
    "name": "acc-name",
    "legal_name": "acc-legal-name",
    "registration_id": "00000000-0000-1000-8000-000f00000300",
    "external_ref": "16bedceb-8b2d-4f82-a973-b0a8d8432708",
    "parent_id": "96b1f750-55d3-4768-a3f8-adffba694a2c"
  }
```

### Create Account Address

| Input | Type | Description |
| --- | --- | --- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
|  **Override Token** |  `string` |  The output of Generate Override Token action to be used with Organizations. |
| **Account ID** | `string` | The unique identifier for an Account. |
| **Account Address Request** |  `string` |  The API request to create an account address. Avoid using `data` parameter in the request. |

For **Account Address Request**, see the following snippet:

```json
  {
    "type": "address",
    "name": "Home",
    "first_name": "Ron",
    "last_name": "Swanson",
    "company_name": "",
    "phone_number": "(555) 555-1234",
    "line_1": "1 Sunny Street",
    "line_2": "Sunny Place",
    "city": "Sunny Town",
    "postcode": "SU33 1YY",
    "county": "Sunnyville",
    "region": "Peterborough",
    "country": "GB",
    "instructions": "Leave in the shed"
  }
```

### Create Customer 

| Input | Type | Description |
| --- | --- | --- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
| **Customer Request** | `string` | The API request to create a customer. Avoid using `data` parameter in the request. |

For **Customer Request**, see the following snippet:

```json
  {
    "type": "customer",
    "name": "Ron Swanson",
    "email": "ron@swanson.com",
    "external_ref": "16bedceb-8b2d-4f82-a973-b0a8d8432708",
    "password": "mysecretpassword"
  }
```

### Create Flow

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Name** | `string` | The name of the flow. |
| **description** | `string` | 	Any description for this flow. |
| **slug** | `string` | A unique slug identifier for the flow. |
| **enabled** | `boolean` | `true` if enabled, `false` if not. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create Flow Entry

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **flow_fields Inputs** | `string` | |
| **flow_slug** | `string` | A unique slug identifier for the flow. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create Hierarchies

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Name** | `string` | The name of the hierarchy. |
| **slug** | `string` | A unique slug for the hierarchy. |
| **Description** | `string` | A description of the hierarchy. |
| **locales** | `string` | The hierarchy details localized in the supported languages. For example, hierarchy names or descriptions. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create Integration

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **name** | `string` | Specifies the name of the integration. |
| **description** | `string` | 	Specifies a description for the integration. |
| **integration_type** | `string` | Specifies how the integration is delivered, either `webhook`, `aws_sqs`, or `stomp`. |
| **enabled** | `boolean` | Specifies whether the integration is enabled. |
| **observes object** | `dynamicfieldselection` | Specifies an array of [observable events](/docs/api/integrations/integrations-introduction#observable-events). |
| **configuration** | `string` | Specifies a [configuration](/docs/api/integrations/create-integration). |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
yarn 
### Create Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. | 
| **Quantity** | `string` | The amount of product available. | 
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create Main Image Relationship

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **File Id** | `string` | The unique identifier of the image file. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create OIDC Profile

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Authentication realm Id** | `string` | The ID for the authentication realm. |
| **OIDC Profile Name** | `string` | The name of the OpenID Connect profile. |
| **OIDC Profile Discovery Url** | `string` | The URL of the OpenID Connect discovery document. |
| **OIDC Profile Client Id** | `string` | The client ID for the OpenID Provider. |
| **OIDC Profile Client Secret** | `string` | The client secret for the OpenID Provider. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create Product

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Name** | `string` | The name of the product. |
| **SKU** | `string` | The unique stock keeping unit of the product. |
| **Slug** | `string` | The unique slug of the product. |
| **Description** | `string` | The description of the product. |
| **Status** | `string` | Whether the product is `live` or `draft`. |
| **Commodity Type** | `string` | The commodity type, either `physical` or `digital`. |
| **MPN** | `string` |  The manufacturer part number of the product. |
| **UPC EAN** | `string` | The universal product code or european article number of the product. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create Template Relationship

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Template Id** | `string` | The unique identifier of the template. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Deallocate Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Quantity** | `string` | The number of products to deallocate. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Decrement Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Quantity** | `string` | The number of products to decrement. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Delete Account

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
| **Account ID** | `string` | The unique identifier for an Account. |

### Delete Account Address

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
| **Account ID** | `string` | The unique identifier for an Account. |
| **Account Address ID** | `string` | The unique identifier for an account address. |

### Delete a Price Currency

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Currency Id** | `string` | The unique identifier of the currency. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Delete a Price in a Pricebook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Pricebook Id** | `string` | The unique identifier of the pricebook. |
| **Price Id** | `string` | The unique identifier of the product price. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Delete Customer

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Customer Id** | `string` | The unique identifier of the customer. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Delete Integration by ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Integration Id** | `string` | The unique identifier of the integration. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Duplicate Hierarchies

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Integration Id** | `string` | The unique identifier of the integration. |
| **Integration Id** | `string` | The unique identifier of the integration. |
| **Integration Id** | `string` | The unique identifier of the integration. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Generate Override Token action

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |

### Generate Token via Password

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
| **Email** | `string` | The customer email. |
| **Password** | `string` | The customer password. |
| **Headers** | `string` | The Bearer token required to get access to the API. |

### Generate Token via OIDC

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
| **Code** | `string` | The code returned from the OpenID Connect Provider authentication. |
| **Redirect Uri** | `string` | The url of the front-end that handles the callback of the token. |
| **Code Verifier** | `string` | The customer password. | The Proof Key for Code Exchange (PKCE) Code Verifier, corresponding to the Code Challenge that was supplied to the Authorization endpoint. [Generating a Code Verifier and Challenge](/guides/How-To/Authentication/get-single-sign-on-customer-token/guides/How-To/Authentication/get-single-sign-on-account-management-token#generate-proof-key-for-code-exchange-pkce-parameters). |
| **Headers** | `string` | The Bearer token required to get access to the API. |

### Get a Catalog Product

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Includes** | `array` | Any related types that must be included in the response. For example, files, main_image, and so on. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Customer Attributes

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get a File

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **File Id** | `string` | The unique identifier of the file. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get a Flow Entry

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Flow Slug** | `string` | A unique slug identifier for the flow. |
| **Entry ID** | `string` | A unique identifier for the entry. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get all Catalog Products

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Includes** | `array` | Any related types that must be included in the response. For example, files, main_image, and so on. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get all Catalogs

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get all Customers

| Input | Type | Description |
|:--- |:--- | :--- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Fields on a Flow

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Flow Slug** | `string` | A unique slug identifier for the flow. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Flow Entries

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Flow Slug** | `string` | A unique slug identifier for the flow. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. |
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Hierarchies

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Catalog Id** | `string` | The unique identifier of the catalog. |
| **Release Id** | `string` | The unique identifier of the catalog release. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. |
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Integrations

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. |
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Nodes (with Catalog ID)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Catalog Id** | `string` | The unique identifier of the catalog. |
| **Release Id** | `string` | The unique identifier of the catalog release. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. |
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All OIDC Profiles

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Authentication Realm Id** | `string` | A unique slug identifier for the authentication realm. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Pricebooks

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Stores

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. |
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Transactions

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Order Id** | `string` | A unique slug identifier for the order. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Variations

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. |
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get A Pricebook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Pricebook Id** | `string` | A unique slug identifier for the pricebook. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get a Transaction by Order ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Order Id** | `string` | A unique slug identifier for the order. |
| **Transaction Id** | `string` | A unique slug identifier for the transaction. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Catalog Releases

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Catalog Id** | `string` | The unique identifier of the catalog. |
| **Release Id** | `string` | The unique identifier of the catalog release. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Currencies

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Customer

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Customer Id** | `string` | The unique identifier of the customer. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Customer Authentication Settings

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Merchant Realm Mapping

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Multiple Files

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **File Ids** | `string` | The unique identifier of the files. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Multiple Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Ids** | `string` | The unique identifier of the products. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Multiple Product by IDs (Shopper Catalog)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Ids** | `string` | The unique identifier of the products. |
| **Includes** | `array` | Any related types that must be included in the response. For example, files, main_image, and so on. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Order by ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Order Id** | `string` | The unique identifier of the order. |
| **Includes** | `array` | Any related types that must be included in the response. For example, files, main_image, and so on. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Orders

Get a page of orders.

| Input | Type | Description |
|:--- |:--- | :--- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. Defaults to 25, unless overridden in store settings.|
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Filter Type** | `string` | The type of filter to apply to this query. All 3 filter fields must be provided or else the filter settings are ignored. |
| **Filter Field** | `string` | The field to specify in the filter. |
| **Filter Field Value** | `string` | The value to specify in the filter. |
| **Includes** | `string` | Any related types that must be included in the response. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Order Items By Order ID

| Input | Type | Description |
|:--- |:--- | :--- |
| **Connection** | `connection` | Elastic Path Composable Commerce connection. |
| **Order Id** | `string` | The unique identifier of the order. |
| **Override Token** | `string` | The output of `Generate Override Token` action to be used with organizations. |

### Update Order

| Input | Type | Description |
| --- | --- | --- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Order Id** | `string` | The unique identifier of the order. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
| **Order Request** |  `string` |  The API request to update an order. Avoid using `data` parameter in the request. |

For **Order Request**, see the following snippet:

```json
  {
    "type": "order",
    "shipping_address": {
      "first_name": "Ron"
    }
  }
```

### Get Product by ID (PXM)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Product by ID (Shopper Catalog)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **EP-Channel** | `string` | The channel, such as website or mobile app. Corresponds to the channel attribute in a [Rule](/docs/api/pxm/catalog/create-rule). |
| **EP-Context-Tag** | `string` | A tag defined in the store, such as clearance. Corresponds to the tag attribute in a [Rule](/docs/api/pxm/catalog/create-rule). |
| **X-MOLTIN-CURRENCY** | `string` | For projects that support multiple currencies, use `x-moltin-currency` that contains the formatting detail for all currencies available to the catalog. |
| **Includes** | `array` | Any related types that must be included in the response. For example, files, main_image, and so on. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Product by ID (with Catalog ID)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Catalog Id** | `string` | The unique identifier of the catalog. |
| **Release Id** | `string` | The unique identifier of the catalog release. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Product by SKU (PXM)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **SKU** | `string` | The unique SKU of the product. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Product by SKU (Shopper Catalog)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **SKU** | `string` | The unique SKU of the product. |
| **EP-Channel** | `string` | The channel, such as website or mobile app. Corresponds to the channel attribute in a [Rule](/docs/api/pxm/catalog/create-rule). |
| **EP-Context-Tag** | `string` | A tag defined in the store, such as clearance. Corresponds to the tag attribute in a [Rule](/docs/api/pxm/catalog/create-rule). |
| **X-MOLTIN-CURRENCY** | `string` | For projects that support multiple currencies, use `x-moltin-currency` that contains the formatting detail for all currencies available to the catalog. |
| **Includes** | `array` | Any related types that must be included in the response. For example, files, main_image, and so on. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Products in Node (With Catalog ID)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Catalog Id** | `string` | The unique identifier of the catalog. |
| **Release Id** | `string` | The unique identifier of the catalog release. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. |
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Organization Id

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Increment Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Quantity** | `string` | The amount of the product to increment. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Switch Session To Organization

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Organization Id** | `string` | The unique identifier of the organization to be switched to when using an organization session token. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Switch Session To Store

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Store Id** | `string` | The unique identifier of the store to be switched to when using an organization session token. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Update a Pricebook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Name** | `string` | Specifies the name of the pricebook. |
| **Description** | `string` | 	Specifies a description for the pricebook. |
| **Pricebook Id** | `string` | The unique identifier of the pricebook. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Update a Price in a Pricebook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Pricebook Id** | `string` | The unique identifier of the pricebook. |
| **SKU** | `string` | Specifies the SKU of the pricebook. |
| **Currencies** | `string` | Specifies the updated currencies for the pricebook. |
| **Sales** | `string` | Specifies the updated sales for the pricebook. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Update Account

| Input | Type | Description |
| --- | --- | --- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. | 
| **Account ID** |  `string` | The unique identifier for an account. |
| **Account Request** |  `string` | The API request to update an account. Avoid using `data` parameter in the request. |

For **Account Request**, see the following snippet:

```json
  {
    "type": "account",
    "name": "acc-name",
    "legal_name": "acc-legal-name",
    "registration_id": "00000000-0000-1000-8000-000f00000300"
  }
```

### Update Account Address

| Input | Type | Description |
| --- | --- | --- |
| **Connection** |  `connection` |  Elastic Path Commerce Cloud connection. |
| **Override Token** |  `string` |  The output of Generate Override Token action to be used with Organizations. |
| **Account ID** |  `string` |  The unique identifier for an Account. | 
| **Account Address ID** |  `string` |  The unique identifier for an account address. |
|  **Account Address Request** |  `string` |  The API request to update an account address. Avoid using `data` parameter in the request. |

For **Account Address Request**, see the following snippet:

```json
  {
    "type": "address",
    "first_name": "Ron"
  }
```

### Update Authentication Realm

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Authentication Realm Id** | `string` | The unique identifier of the authentication realm. |
| **Redirect URL** | `string` | An array of [Storefront](/docs/developer-tools/storefront) URIs that can start Single Sign On authentication. These URIs must follow the rules for [redirection endpoints in OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2). All URIs must start with `https://` except for `http://localhost`. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Update Customer 

| Input                | Type | Description |
|----------------------| --- | --- |
| **Connection**       |  `connection` |  Elastic Path Commerce Cloud connection. |
| **Override Token**   |  `string` |  The output of Generate Override Token action to be used with Organizations. |
| **Customer ID**      |  `string` |  The unique identifier for a customer. |
| **Customer Request** |  `string` |  The API request to update a customer. Avoid using `data` parameter in the request. |

For **Customer Request**, see the following snippet:

```json
  {
    "type": "customer",
    "email": "ron@swanson.com"
  }
```

### Update Flow Entry

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Entry Id** | `string` | The unique identifier of the entry. |
| **Flow Fields** | `string` | The flow fields to update. |
| **Flow Slug** | `string` | The unique slug of the flow whose entry you want to update. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Update Merchant Realm Mapping

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Authentication Realm Id** | `string` | The unique identifier of the authentication realm. |
| **Merchant Mapping Prefix** | `string` | The store prefix that is assigned to this merchant realm mapping. This can be null if a store prefix has not been assigned. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Update OIDC Profile

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Authentication realm Id** | `string` | The ID for the authentication realm. |
| **OIDC Profile Name** | `string` | The name of the OpenID Connect profile. |
| **OIDC Profile Discovery Url** | `string` | The URL of the OpenID Connect discovery document. |
| **OIDC Profile Client Id** | `string` | The client ID for the OpenID Provider. |
| **OIDC Profile Client Secret** | `string` | The client secret for the OpenID Provider. |
| **OIDC Profile Id** | `string` | The ID for the OIDC Profile. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Update Product

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Product Id** | `string` | The unique identifier of the product. |
| **Name** | `string` | The name of the product. |
| **SKU** | `string` | The unique stock keeping unit of the product. |
| **Slug** | `string` | The unique slug of the product. |
| **Description** | `string` | The description of the product. |
| **Status** | `string` | Whether the product is `live` or `draft`. |
| **Commodity Type** | `string` | The commodity type, either `physical` or `digital`. |
| **MPN** | `string` |  The manufacturer part number of the product. |
| **UPC EAN** | `string` | The universal product code or european article number of the product. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Promotion by Id

Find a promotion by unique identifier.

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Promotion ID** | `string` | The ID of the promotion. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Promotion by Name

Find a promotion with the given name.  The action uses an exact, case-sensitive match to find the promotion.

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Promotion Name** | `string` |  The exact case-sensitive name of the promotion. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get All Promotions

| Input | Type | Description |
|:--- |:--- | :--- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Limit** | `string` | The maximum number of records per page for this response. You can set this value up to 100. Defaults to 25, unless overridden in store settings.|
| **Offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. Default is zero. |
| **Filter Type** | `string` | The type of filter to apply to this query. All 3 filter fields must be provided or else the filter settings are ignored. |
| **Filter Field** | `string` | The field to specify in the filter. |
| **Filter Field Value** | `string` | The value to specify in the filter. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Account by ID

| Input | Type | Description |
|:--- |:--- | :--- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
| **Account ID** | `string` | The unique identifier for an Account. |

### Get Account Address by ID

| Input                  | Type         | Description                                                                 |
|:-----------------------|:-------------|:----------------------------------------------------------------------------|
| **Connection**         | `connection` | Elastic Path Commerce Cloud connection.                                     |
| **Override Token**     | `string`     | The output of Generate Override Token action to be used with Organizations. |
| **Account ID**         | `string`     | The unique identifier for an Account.                                       |
| **Account Address ID** | string`      | The unique identifier for an account address.                               |

### Get Account Attributes

| Input | Type | Description |
|:--- |:--- | :--- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Get Paged Accounts

| Input                  | Type         | Description                                                                                                              |
|:-----------------------|:-------------|:-------------------------------------------------------------------------------------------------------------------------|
| **Connection**         | `connection` | Elastic Path Commerce Cloud connection.                                                                                  |
| **Override Token**     | `string`     | The output of Generate Override Token action to be used with Organizations.                                              |
| **Limit**              | `string`     | The maximum number of records per page for this response. You can set this value up to 100.                              |
| **offset**             | `string`     | The current offset by number of records, not pages. Offset is zero-based.                                                |
| **Filter Type**        | `string`     | The type of filter to apply to this query. All 3 filter fields must be provided or else the filter settings are ignored. |
| **Filter Field**       | `string`     | The field to specify in the filter.                                                                                      |
| **Filter Field Value** | `string`     | The value to specify in the filter.                                                                                      |

### Get Paged Account Addresses

| Input | Type | Description |
|:--- |:--- | :--- |
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |
| **Limit** | `string` |  The maximum number of records per page for this response. You can set this value up to 100. |
| **offset** | `string` | The current offset by number of records, not pages. Offset is zero-based. |
| **Account ID** | `string` | The unique identifier for an Account. |

### Get Paged Customers

| Input                  | Type         | Description                                                                                                              |
|:-----------------------|:-------------|:-------------------------------------------------------------------------------------------------------------------------|
| **Connection**         | `connection` | Elastic Path Commerce Cloud connection.                                                                                  |
| **Limit**              | `string`     | The maximum number of records per page for this response. You can set this value up to 100.                              |
| **offset**             | `string`     | The current offset by number of records, not pages. Offset is zero-based.                                                |
| **Filter Type**        | `string`     | The type of filter to apply to this query. All 3 filter fields must be provided or else the filter settings are ignored. |
| **Filter Field**       | `string`     | The field to specify in the filter.                                                                                      |
| **Filter Field Value** | `string`     | The value to specify in the filter.                                                                                      |

### Get Promotion Code Usages

Get the usages details for a given promotion code.

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Promotion ID** | `string` | The ID of the promotion. |
| **Promotion Code** | `string` | The promotion code to query for usage details. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

### Create Promotion Code

Creates a new promotion code for an existing promotion.

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Elastic Path Commerce Cloud connection. |
| **Promotion ID** | `string` | The ID of the promotion. |
| **Promotion Code** | `string` | The new promotion code to create. |
| **Allowed Customer Ids** | `string` | The UUIDs of customers that are allowed to redeem the promotion. |
| **Max Usage Count** | `string` | The maximum number of times a promotion can be applied. |
| **Consume Unit** | `string` | Indicates how the promotion should be applied. |
| **Override Token** | `string` | The output of Generate Override Token action to be used with Organizations. |

---

## Google Content API for Shopping Component

You can use the Google Content API component to upload your Commerce products so that they automatically appear in Google Search results in the Shopping tab.

## Connections

Once your Google Merchant account is set-up, you need to create an API authentication key for the Content API. The API key is some JSON data which you must save securely and not check-in to source control. You need the `client_email` and `private_key` from this JSON file when you configure the integration. 

| Option | Description                            |
|:------------------------------------|:---------------------------------------|
| **client_email**                    | The email address associated with your Google Merchant account. |
| **private_key**                     | Your Google Merchant account private key. |
| **google_merchant_id**              | Your Google Merchant account ID. |

For more information, see [Merchant Center - Google for Retail](https://www.google.com/retail/solutions/merchant-center/).

## Actions

The component has the following action.

### Upload Products to Google

| Input | Type | Description |
|:--- |:--- | :--- | 
| **The client email value of service account key file**  | `string` | The email address associated with your Google Merchant account. |
| **The private_key of service account key file** | `string` | Your Google Merchant account private key. | 
| **The JSON for the custom batch request** | `string` | The JSON you want to send to Google Merchant Center. | 
| **Log Level** | `string` | The level of logging. |

---

## Import Node Product Associations Component

You can use the Commerce Catalog Publish component to update Commerce node product association data in your Commerce store.

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Actions

The component has the following action.

### Load Node Product Association

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Node Product Associations** | `string` | The node product association data. See [Node Product Association Import Format](/docs/composer/integration-hub/store-management/node-product-association#node-product-association-import-integration-file-format). | 
| **Max Hierarchy Depth** | `string` | The depth of parent/child levels you want. The default is **3**. | 
| **Log Level** | `string` | The level of logging. |

---

## Inventory Loader Component

You can create and update inventory data in your Commerce store using the Inventory Loader component. 

- You can create inventory when an inventory object does not exist for a product.
- You can update inventory values based on the strategy you select when an inventory object exists for a product.

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Actions

The component has the following action.

### Load Products Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Inventories** | `text` | The data that you provide to the Inventory Import integration must conform to [JSON Lines](https://jsonlines.org/) text format and conform to the model described [here](/docs/composer/integration-hub/store-management/inventory-import#inventory-import-integration-file-format). | 
| **Product Batch Size** | `string` | The maximum product batch size is 100. If you configure the Product Batch Size to a value greater than 100, the integration automatically adjusts the value to 100. The default is **100**. | 
| **Log Level** | warn | The level of logging. |

---

## JSON Form Library Component

This component provides pre-built configuration forms using [JSON Forms](https://jsonforms.io/). These forms provide sophisticated configuration elements that you can leverage when creating the configuration section for your Commerce integrations. The following pre-built forms are available in the component:

* Catalog Webhook Selector Multi-Select
* Order Webhook Selector Multi-Select
* Order Webhook Selector Single
* Catalog Webhook Selector Single-Select
* Customer Webhook Selector Multi-Select
* Customer Webhook Selector Single-Select
* Catalog And Storefront Mapper
* Catalog Include And Exclude Config
* Single Catalog Selection
* Hierarchy Selector
* Pricebook Selector

The following steps describe how to find JSON Form Library component in Commerce Manager while configuring your integration.

1. Go to **COMPOSER > Builder**.
1. Select **+Add Integration**. The **Configure new integration** page is displayed.
1. Choose the required option from the **Configure new integration** page to create a new integration.
1. To add JSON Form Library component, go to **Configuration Wizard**.
1. Select **+Config variable** to add a config variable.
1. In the **Data Type** field, select **JSON Form** from the list.

   In the **Data Source** field, you can now see the JSON Form Library Component. 

## Actions

This component has the following actions.

### Catalog Webhook Selector (Multi-select)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Catalog Event List**  | `string` | A list of catalog events. | 

### Catalog Webhook Selector (Single-select)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Catalog Event List**  | `string` | A list of catalog events. | 

### Order Webhook Selector (Multi-select)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Order Event List**  | `string` | A list of order events. | 

### Order Webhook Selector (Single-select)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Order Event List**  | `string` | A list of order events. | 

### Customer Webhook Selector (Multi-select)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Customer Event List**  | `string` | A list of customer events. | 

### Customer Webhook Selector (Single-select)

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Customer Event List**  | `string` | A list of customer events. | 

### Catalog and Storefront Mapper 

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 

### Catalog Include/Exclude Config

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. |

---

## Elastic Path JSON Schema Component

This component provides actions to work with JSON Schemas.

## Actions

This component has the following action.

### Validate JSON Object with Schema

This action provides a way to validate the format of a given JSON Object against a given JSON Schema using the [jsonschema](https://www.npmjs.com/package/jsonschema) library.  The result is returned as a [ValidatorResult](https://github.com/tdegrunt/jsonschema/blob/b53e5853d88763b3de57be0250f46a55445789f6/lib/helpers.js#L33) object.  The `errors` array field on the result will be empty if the object was successfully validated.

| Input | Type | Description |
|:--- |:--- | :--- |
| **JSON Object to Validate**  | `code` | The JSON object to validate. |
| **JSON Schema**  | `code` | The JSON Schema object to use for validation. |
| **Throw Error If Validation Fails** | `boolean` | Enable this flag if you want a hard stop if the validation fails.  Disable to handle the validation failure directly in your integration. |
| **Log Level**  | `string` | The level of component logging. |

---

## JSON File Streamer Component

This component allows you to take Commerce data and stream the data to a JSON file. The JSON file can be broken smaller batches for easier processing.

## Actions

This component has the following action.

### JSON File Streamer

| Input | Type | Description |
|:--- |:--- | :--- | 
| **JSON File URL**  | `string` | A URL to a JSON file. | 
| **Batch Consumer API URL**  | `string` | An API URl for batch consumer. | 
| **Batch Consumer API Key**  | `string` | An API key for batch consumer. | 
| **Batch Size**  | `string` | The number of pages to group into a single batch. Default is **250**. | 
| **Batch Consumer Concurrency**  | `string` | The default is **10**. | 
| **Taxonomy**  | `string` | The taxonomy. | 
| **Mapping**  | `string` | The mapping. | 
| **Catalog Attributes**  | `string` | The catalog attributes. | 
| **Meta**  | `string` | The meta data. | 
| **Offset**  | `string` | Use the page offset to get additional pages for your content. | 
| **Log Level**  | `string` | The level of logging. | 
| **Enabled Downstream Response**  | `boolean` | `true` if you want to enable downstream response. |

---

## Node Loader Component

You can use the Commerce Node Loader component to import Commerce node data to your Commerce store. The Commerce Node Loader component can import:

- Node data files of any size. 
- Localized node names and descriptions.

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Actions

The component has the following action.

### Load Nodes Product 

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Nodes** | `text` | The data that you provide to the Node Loader component must conform to [JSON Lines](https://jsonlines.org/) text format and conform to the model described [here](/docs/composer/integration-hub/store-management/node-import#node-import-integration-file-format). | 
| **Max Hierarchy Depth** |`string` | The depth of parent/child levels you want. The default is **3**. | 
| **Log Level** | `string` | The level of logging. |

---

## Onport Component

Onport supports marketplace and/or dropship vendor models. Integrating Onport with Commerce means you can enable support for marketplace and dropship vendor models in Commerce. The **Onport Integration** supports the following features.

- **Product** changes in Onport causes webhook events to be generated to change product data in Commerce.
- **Inventory** changes in Onport causes webhook events to be generated that increment or decrement inventory in Commerce.
- **Order** changes in Commerce like creating, updating, fulfilling and so on, causes webhook events to be generated that cause orders to be created, updated, fulfilled and so on, in Onport. The following Commerce event types can be used to generate webhook events.

    - `order.created`
    - `order.updated`
    - `order.fulfilled`
    - `order.paid`
    - `order.authorized`

- **Split Orders** orders generated in Commerce causes webhook events to be generated in Onport that allow Onport to split an order based on vendors. 

## Connections

Collect the following setup information from Onport.

| Option | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Onport API Base URL. Default value is `https://api.jetti.io/api`. |
| **API Key**                       | Your Onport API Key. |

## Actions

The component has the following actions.

### Manual Sale 

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Onport connection. | 
| **Channel ID** | `string` | Your Onport Channel ID. See [Create an Onport Channel ID](/docs/composer/integration-hub/order-marketplace-inventory/onport#create-an-onport-channel-id). | 
| **Order Request** | `string` | As part of the Onport Integration, changes in orders in Commerce automatically updates order data in Onport. See [Synchronizing Commerce Order Data With Onport Order Data](/docs/composer/integration-hub/order-marketplace-inventory/onport#synchronizing-commerce-order-data-with-onport-order-data). | 

### Update Inventory Endpoint

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Onport connection. | 
| **Custom Channel ID** | `string` | Your Onport Channel ID. See [Create an Onport Channel ID](/docs/composer/integration-hub/order-marketplace-inventory/onport#create-an-onport-channel-id). | 
| **Inventory Endpoint** | `string` | Changes in inventory in Onport automatically updates inventory data in Commerce. | 

### Update Publishing Endpoint

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Onport connection. | 
| **Custom Channel ID** | `string` | Your Onport Channel ID. See [Create an Onport Channel ID](/docs/composer/integration-hub/order-marketplace-inventory/onport#create-an-onport-channel-id). | 
| **Publishing Endpoint** | `string` | As part of the Onport Integration, changes in product data in Onport automatically updates product data in Commerce. See [Synchronizing Onport Product Data With Commerce Product Data](/docs/composer/integration-hub/order-marketplace-inventory/onport#synchronizing-onport-product-data-with-commerce-product-data). |

### Update Price Endpoint

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Onport connection. | 
| **Custom Channel ID** | `string` | Your Onport Channel ID. See [Create an Onport Channel ID](/docs/composer/integration-hub/order-marketplace-inventory/onport#create-an-onport-channel-id). | 
| **Price Endpoint** | `string` | As part of the Onport Integration, changes in price in Onport automatically updates price data in Commerce. See [Synchronizing Onport Price Data With Commerce](/docs/composer/integration-hub/order-marketplace-inventory/onport#synchronizing-onport-price-data-with-commerce). | 

### Update Fulfilment Endpoint

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Onport connection. | 
| **Custom Channel ID** | `string` | Your Onport Channel ID. See [Create an Onport Channel ID](/docs/composer/integration-hub/order-marketplace-inventory/onport#create-an-onport-channel-id). | 
| **Fulfilment Endpoint** | `string` | As part of the Onport Integration, changes in fulfilment in Onport automatically updates fulfilment data in Commerce. See [Synchronizing Onport Fulfilment Data With Commerce](/docs/composer/integration-hub/order-marketplace-inventory/onport#synchronizing-onport-fulfilment-data-with-commerce). | 

### Get Sale Return Items

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Onport connection. | 
| **Query Parameters** | `object` | Key value pair, for example, key = where[saleReturnId] and value = 282309. |

---

## Pimberly Component

You can integrate Commerce with Pimberly using the Pimberly component. This means you can synchronize catalog data such as products, price, images, and categories between Commerce and Pimberly.

## Connections

You need the following to interact with Pimberly.

| Option | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Pimberly API Base URL. Default value is `https://sandbox.pimber.ly/api/v2.2`. |
| **API Key**                       | Your Pimberly API Key. Login to your Pimberly account to retrieve your API Keys. |
| **Webhook URL**               | Your Pimberly webhook URL. Default value is `https://sandbox-api.pimberly.io`. |

## Actions

The component has the following actions.

### Create a Webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Pimberly Connection. | 
| **enabled** | `boolean` | If webhook is enabled. | 
| **Action** | `dynamicfieldselection` | Set up your webhook actions depending on your requirements. | 
| **URL** | `string` |  The webhook URL. | 

### Delete a Webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Pimberly Connection. | 

### Get all Products

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Pimberly Connection. | 
| **Max Id** | `string` | The maximum ID. | 
| **Limit** | `string` | The product limit. | 

### Get a Product

| Input | Type | Description |
|:--- |:--- | :--- | 
|**Connection** | `connection` | Pimberly Connection. | 
| **Product Id** | `string` | The unique identifier of the product. | 

### Get a Product Category

| Input | Type | Description |
|:--- |:--- | :--- | 
|**Connection** | `connection` | Pimberly Connection. | 
| **Product Id** | `string` | The unique identifier of the product. | 

### Get a Webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
|**Connection** | `connection` | Pimberly Connection. | 

### Get Categories for Products

| Input | Type | Description |
|:--- |:--- | :--- | 
|**Connection** | `connection` | Pimberly Connection. | 
| **Products** | `dynamicfieldselection` | The products whose categories you want to retrieve. |

### Get Child Products

| Input | Type | Description |
|:--- |:--- | :--- | 
|**Connection** | `connection` | Pimberly Connection. | 
| **Product Id** | `string` | The unique identifier of the product. | 

### Get Parent Products

| Input | Type | Description |
|:--- |:--- | :--- | 
|**Connection** | `connection` | Pimberly Connection |
| **Product Id** | `string` | The unique identifier of the product. | 

### Transform Product

| Input | Type | Description |
|:--- |:--- | :--- | 
|**Connection** | `connection` | Pimberly Connection | 
| **Products** | `dynamicfieldselection`  | The products you want to transform. | 
| **Product Type Template** | `dynamicfieldselection` | The product type templates you want to transform. | 
| **Product Template** | `dynamicfieldselection` | The product templates you want to transform. |
| **Variation Template** | `dynamicfieldselection` | The variation template you want to transform. |
| **Product Type** | `string`  | The product type you want to transform. |

---

## Postmark Component

You can use the Postmark component to send emails to single or multiple recipients.

## Connections

You need your **Postmark-API-Key** which is the Postmark API Key generated in your Postmark account to access dynamic email templates in Postmark.

## Actions

The component has the following actions.

### Configure Postmark Integrations

| Input | Type | Description |
|:--- |:--- | :--- | 
| **EPCC Postmark Connection**  | `string` | The EPCC Postmark connection. | 
| **Postmark Integration Webhook URL**  | `string` | The webhook URl that is displayed in Integrations Hub when you activate the integration. | 
| **Postmark Event-Mapping** | `string` | Mapping of information between Commerce Manager and Postmark is done through a combination of event names and JSON values. See [Configuring Event-Mapping Configurations](/docs/composer/integration-hub/marketing-communication/postmark). | 
| **Log Level** | `string` | The level of logging. | 
| **Webhook API Key** | `string` | The webhook key that is displayed in Integrations Hub when you activate the integration. | 

### Hash the Client Secret

| Input | Type | Description |
|:--- |:--- | :--- | 
| **EPCC Postmark Connection**  |  | The EPCC Postmark connection. |  
| **Log Level** | `string` | The level of logging. | 

#### Output Example

### Hydrate event mappings for the incoming event data

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Event JSON**  | `string` | The payload from the event. See [Integration Payload](/docs/api/integrations/integrations-introduction#example-typical-payload). | 
| **Postmark Event-Mapping** | `string` | Mapping of information between Commerce Manager and Postmark is done through a combination of event names and JSON values. See [Configuring Event-Mapping Configurations](/docs/composer/integration-hub/marketing-communication/postmark#configuring-event-mapping-configurations). | 
| **Log Level** | `string` | The level of logging. | 

### Returns the templated emails to the caller without invoking Postmark

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Event configuration hydrated array**  | `string` | The output of the applyEventMappingToEventAction action. | 
| **Log Level** | `string` | The level of logging. |

### Send a templated email via Postmark Email

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Event Configuration Hydrated Array**  | `string`  | The payload from the event. See [Integration Payload](/docs/api/integrations/integrations-introduction). | 
| **Postmark API Key** | `string` | Your **Postmark-API-Key** which is the Postmark API Key generated in your Postmark account. | 
| **Log Level** | `string` | The level of logging. | 

### Take action based on email result

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Error on Fail**  | `boolean` | An error is returned when there is a failure in sending emails to recipients. | 
| **Log email errors**  | `boolean` | Log the errors that are returned when there is a failure in sending emails to recipients. | 
| **Postmark Results**  | `string` | Postmark sends back results to the Postmark integration when emails are sent to recipients. | 
| **Log Level** | `string` | The level of logging. | 

### Validate Event Mappings

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Postmark Event-Mapping** | `string` | Mapping of information between Commerce Manager and Postmark is done through a combination of event names and JSON values. See [Configuring Event-Mapping Configurations](/docs/composer/integration-hub/marketing-communication/postmark#configuring-event-mapping-configurations). | 
| **Log Level** | `string` | The level of logging. |

---

## Price Loader Component

You can use the Commerce Price Loader component to import Commerce price data from one Commerce store to another. You can import:

- Price data files of any size. 
- Tier and sale pricing associated with prices.

:::caution

The Price Import integration does not support bundles.

:::

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Actions

The component has the following actions.

### Load Prices

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Prices** | `text` | The data that you provide to the Price Loader component must conform to JSON Lines text format and conform to the model [here](/docs/composer/integration-hub/store-management/price-import#price-import-integration-file-format). |
| **Log Level** | `string` | The level of logging. |

### Load Pricebooks

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Price Books** | `text` | The data that you provide to the Price Loader component must conform to JSON Lines text format and conform to the model [here](/docs/composer/integration-hub/store-management/price-import#price-import-integration-file-format). | 
| **Log Level** | `string` | The level of logging. |

---

## Product Loader Component

You can use the Commerce Product Loader component to to import Commerce product data from one Commerce store to another. The Commerce Product Import utility can import:

- Product data files of any size. 
- Product variations. 
- Any media files available with products.
- Localized product names and descriptions.

:::caution

You cannot import bundles using the Product Import integration.

:::

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key  | Description                  |
|:------------------|:-----------------------------|
| **API Base URL**  | Your Commerce API Base URL.  |
| **Client ID**     | Your Commerce Client ID.     |
| **Client Secret** | Your Commerce Client Secret. |

## Actions

The component has the following actions.

### Load Products

| Input           | Type         | Description                                                                                                                                                                                                                                |
|:----------------|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
| **Connection**  | `connection` | Commerce connection.                                                                                                                                                                                                                       | 
| **Products**    | `text`       | The data that you provide to the Product Import Integration must conform to JSON Lines text format and conform to the model [here](/docs/composer/integration-hub/store-management/product-import#product-import-integration-file-format). |
| **Update Data** | `boolean`    | Enabled if we are running in MERGE mode to merge the inbound products with the current products. Default: off                                                                                                                              |
| **Log Level**   | `string`     | The level of logging.                                                                                                                                                                                                                      |
| **Variations**  | `text`       | The data that you provide to the Product Import Integration must conform to JSON Lines text format and conform to the model [here](/docs/composer/integration-hub/store-management/product-import#product-import-integration-file-format). |

### Gets Variations

| Input          | Type         | Description           |
|:---------------|:-------------|:----------------------| 
| **Connection** | `connection` | Commerce connection.  | 
| **Log Level**  | `string`     | The level of logging. | 

### Update Variation Options

| Input          | Type         | Description                                                                                                                                                                                                                                |
|:---------------|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
| **Connection** | `connection` | Commerce connection.                                                                                                                                                                                                                       | 
| **Variations** | `text`       | The data that you provide to the Product Import Integration must conform to JSON Lines text format and conform to the model [here](/docs/composer/integration-hub/store-management/product-import#product-import-integration-file-format). | 
| **Products**   | `text`       | The data that you provide to the Product Import Integration must conform to JSON Lines text format and conform to the model [here](/docs/composer/integration-hub/store-management/product-import#product-import-integration-file-format). | 
| **Log Level**  | `string`     | The level of logging.                                                                                                                                                                                                                      |

---

## Salsify Component

You can integrate Commerce with Salsify using the Salsify component. This means you can synchronize catalog data such as products, price, images, and categories between Commerce and Salsify.

## Connections

You need the following to interact with Salsify.

| Option | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Salsify API Base URL. Default value is `https://app.salsify.com/api/v1/orgs/`. |
| **API Key**                       | Your Salsify API Key. To collect your API key, log in to your Salsify account, go to **My Profile > API Access**, and click **Show API Key**. |
| **Organization ID**               | Your Salsify Organization ID. |

## Actions

The component has the following actions.

### Bulk Upsert Images

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Salsify Connection. | 
| **Images Request** | `dynamicfieldselection` | |

### Bulk Upsert Products

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Salsify Connection. | 
| **Products Request** | `dynamicfieldselection` | |

### Create Webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Salsify Connection. | 
| **Webhook Request** | `dynamicfieldselection` | | 

### Get all Products

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Salsify Connection. | 
| **Per Page Value** | `string` | | 
|  **Cursor Value** | `string` | | 

### Get all Webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Salsify Connection. | 

### Get a Product

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Salsify Connection. | 
| **Product ID** | `string` | The unique identifier of the product. | 

### Get Image by ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Salsify Connection | 
| **Image ID** | `string` | The unique identifier of the image. | 

### Get Images by ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Salsify Connection. |
| **Image IDs** | `string` | The unique identifiers of all images. | 

### Update Webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Salsify Connection. | 
| **Webhook Request** | `dynamicfieldselection` | The unique identifiers of all images. | 
| **webhookId** | `string` | |

---

## Sendgrid Component

Integrating with SendGrid allows you to send emails to your customers when events in Commerce are triggered. For example, you can send a customer registration email when you create a customer in Commerce, or send an order confirmation email when an order is created.

## Connections

You need the **SendGrid API Key ID** which is the API Key for your SendGrid account. In SendGrid, API keys are found in **Settings** > **API Keys**.

## Actions

The component has the following actions.

### Configure Sendgrid Integrations

| Input | Type | Description |
|:--- |:--- | :--- |
| **EPCC Sendgrid Connection**  | `connection` | The EPCC Sendgrid connection. | 
| **Sendgrid Integration Webhook URL**  | `string` | The Sendgrid webhook URL that is displayed in Integrations Hub when you activate the integration. |
| **Sendgrid Event-Mapping** | `string` | Mapping of information between Commerce Manager and Postmark is done through a combination of event names and JSON values. See [Configuring Event-Mapping Configurations](/docs/composer/integration-hub/marketing-communication/sendgrid#configuring-event-mapping). | 
| **Log Level** | `string` | The level of logging. | 

### Extract all JSONATA Mappings

| Input | Type | Description |
|:--- |:--- | :--- |
| **Event JSON**  | `string` | The payload from the event. See [Integration Payload](/docs/api/integrations/integrations-introduction). | 
| **Sendgrid Event-Mapping** | `string` | Mapping of information between Commerce Manager and Postmark is done through a combination of event names and JSON values. See [Configuring Event-Mapping Configurations](/docs/composer/integration-hub/marketing-communication/sendgrid#configuring-event-mapping). | 
| **Log Level** | `string` | The level of logging. | 

### Send a templated email via Sendgrid Email 

| Input | Type | Description |
|:--- |:--- | :--- |
| **Event Type**  | `string` | The EPCC Event Type. See [Observable Events](/docs/api/integrations/integrations-introduction#observable-events). | 
| **Sendgrid Event-Mapping** | `string` | Mapping of information between Commerce Manager and Postmark is done through a combination of event names and JSON values. See [Configuring Event-Mapping Configurations](/docs/composer/integration-hub/marketing-communication/sendgrid#configuring-event-mapping). | 
| **Event Map Results**  | `string` | The event map results | 
| **Sendgrid API Key**  | `string` | The API Key for your SendGrid account. | 
| **Log Level** | `string` | The level of logging. |

---

## Store Configuration Loader Component

The Commerce Store Configuration Loader enables you to export and/or import resources from one Commerce store to another. This is useful if, for example, you want to copy a configuration from a store in a development environment to a store in a production environment. 

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Actions

The component has the following actions.

### Delete Store Configuration 

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection`  | Commerce connection. | 
| **Log Level** | `string` | The level of logging. | 
| **Max Pages** | `string` | The page size to query when deleting large volumes of products. Maximum value is **100**. | 
| **Batch Size** |`string`  | the maximum number of batches to delete at one time. Leave blank to delete all batches. For example, if you set the **Delete Batch Limit** to 5, the first 5 batches of products are deleted. | 
| **Configuration Policy** | `code` | **Delete** existing resources. The `Delete Asynchronous Flow` provides a webhook trigger that invokes the Store Configuration Orchestrator's Delete Action. The asynchronous response is a single data element containing the remaining products. See [Commerce Store Configuration Orchestrator](/docs/composer/integration-hub/store-management/store-configuration). |

### Export Store Configuration

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Log Level** | `string` | The level of logging. | 
| **Configuration Policy** | `code` | **Export** a store configuration to a JSON file.  The `Export Synchronous Flow` provides a webhook trigger that invokes the Store Configuration Orchestrator's Export Action and returns the exported store configuration in a JSON file. See [Commerce Store Configuration Orchestrator](/docs/composer/integration-hub/store-management/store-configuration). | 

### Import Store Configuration

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **JSON Configuration Object**  | `string` | The JSON configuration object. | 
| **Environment**  | `string` | During an import, you can specify resources by environment. This allows you to have resources for your production and development environments in the same JSON file. When you perform a Store Configuration Orchestrator Import Action, you can specify the environment whose resources you want to import. A Store Configuration Orchestrator Import Action always imports resources from the `common` environment. If no environment is specified, only resources from the `common` environment are loaded. See [Configuring the Store Configuration Orchestrator Integration](/docs/composer/integration-hub/store-management/store-configuration#configuring-the-store-configuration-orchestrator-integration). | 
| **Log Level** | `string` | The level of logging. | 
| **Configuration Policy** | `code` | **Import** a store configuration from one store to another. The `Import Asynchronous Flow` provides a webhook trigger that accepts a JSON payload containing the store configuration. The Store Configuration Orchestrator Import Action executes and passes the JSON request to apply the imported configurations to a store. See [Commerce Store Configuration Orchestrator](/docs/composer/integration-hub/store-management/store-configuration). |

---

## Supplementary Component

You can use the Commerce supplementary component to import rich media asset associated with products, such as product images or a file containing additional product details.

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Actions

The component has the following actions.

### Get Image Detail

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Payload** | `dynamicfieldselection` | The images to retrieve. | 
| **URL Prefix** | `string` | The image URL prefix. | 

### Build Taxonomy

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Algolia Mappings** | `dynamicfieldselection` | The Algolia mappings to build. |
| **URL Prefix** | `string` | The URL prefix.  | 
| **Release Details** | `dynamicfieldselection` | The release details. |

---

## Utilities Component

You can use the Commerce supplementary component to load product, inventory and catalog data into an Commerce store.

## Connections

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Actions

The component has the following actions.

### Load Product

| Input | Default | Notes | Example |
|:--- |:--- | :--- | :--- |
| **Connection**  | `connection` | Commerce connection. | 
| **Product Request** | `code` | The products to load. |

### Load Inventory

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Product ID** | `string` | The unique identifier of the product whose inventory you want to update. | 
| **Inventory** | `string` | The [inventory](/docs/api/pxm/inventory/create-product-stock). | 

### Load Webhook Integration

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Name** | `string` | The name of the integration. | 
| **Description** | `string` | The integration description. | 
| **Enabled** | `boolean` | `true` if the integration is enabled. | 
| **Webhook URL** | `string` | The webhook URL to display in the Integrations Hub when the integration is enabled. | 
| **Secret** | `string`  | The Commerce secret. | 
| **Events** | `string` | The events. | 
| **Limit** | `string` | The maximum event limit. | 

### Get Product by SKU with main image

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **SKU** | `string` |  | 

### Get Product by ID with Catalog ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. |
| **Product ID** | `string` | A unique identifier of a product. | 
| **Catalog ID** | `string` | A unique identifier of a catalog. | 
| **Release ID** | `string` | A unique identifier of a release. | 

### Get Catalog Releases

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection**  | `connection` | Commerce connection. | 
| **Catalog ID** | `string` | A unique identifier of a catalog. | 
| **Release ID** | `string` | A unique identifier of a release. |

---

## Yotpo Component

You can integrate Commerce with Yotpo enabling your customers to provide ratings and reviews in the storefront for the products they purchased. You can also sync the customer feedback with any search provider that you use; this displays the average customer ratings and reviews received for a product in the storefront.

## Connections

You need the following to interact with Yotpo.

- **Token URL**: The API token URL of your Yotpo account. By default, the value is `https://api.yotpo.com/oauth/token`.
- **Client ID**: Your Yotpo Client ID. In Yotpo, it might be mentioned as **Store ID** or **App ID**.
- **Client Secret**: Your Yotpo Client Secret.

## Actions

The component has the following actions.

### Get review by ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Review ID** | `string` | A unique identifier of a review. | 
| **Log Level** | `string` | The level of logging. | 

### Get product by external ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **External IDs** | `string` |  A unique external ID. | 
| **Log Level** | `string` | The level of logging. | 

### Create product

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Product Request** | `dynamicfieldselection` | The products to create. | 
| **Log Level** | `string` | The level of logging. | 

### Update a Product

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Product Request** | `dynamicfieldselection` | The products to update. | 
| **Log Level** | `string` | The level of logging. | 

### Get a variant by external ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Product Id** | `string` | The unique identifier of the product. | 
| **External Ids** | `string` | The external IDs whose vairants you want retrieve. | 
| **Log Level** | `string` | The level of logging. | 

### Create a variant

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Product Id** | `string` | The unique identifier of the product. | 
| **Variant Request** | `dynamicfieldselection` | The variants you want to create. | 
| **Log Level** | `string` | The level of logging. | 

### Update a variant

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Product Id** | `string` | The unique identifier of the product. | 
| **Variant Id** | `string` | The unique identifier of the variant. | 
| **Variant Request** | `dynamicfieldselection` | The variants you want to update. | 
| **Log Level** | `string` | The level of logging. | 

### Get product review summary by external ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo Connection. | 
| **Product Id** | `string` | The unique identifier of the product. | 
| **Log Level** | `string` | The level of logging. | 

### Get webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Log Level** | `string` | The level of logging. | 

### Create webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. |
| **Event Name** | `string` | The event name. | 
| **Webhook URL** | `string` | The URL of the webhook to be displayed in Integrations Hub when an integration is active. | 
| **Log Level** | `string` | The level of logging. | 

### Update webhook

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. |
| **Event Name** | `string` | The event name. | 
| **Webhook URL** | `string` | The URL of the webhook to be displayed in Integrations Hub when an integration is active. | 
| **Webhook ID** | `string` | The ID of the webhook to be displayed in Integrations Hub when an integration is active. | 
| **Log Level** | `string` | The level of logging. | 

### Get order by external ID

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **External IDs** | `string` | The external Ids of the orders you want to retrieve. | 
| **Log Level** | `string` | The level of logging. | 

### Create order

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Order Request** | `dynamicfieldselection` | The order that you want to create. | 
| **Log Level** | `string` | The level of logging. | 

### Update order

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Order Request** | `dynamicfieldselection` | The order that you want to update. | 
| **Order Id** | `string` | The unique identifier of the order. | 
| **Log Level** | `string` | The level of logging. | 

### Upsert customer

| Input | Type | Description |
|:--- |:--- | :--- | 
| **Connection** | `connection` | Yotpo connection. | 
| **Customer Request** | `dynamicfieldselection` | The customer you want to upsert. | 
| **Log Level** | `string` | The level of logging. |

---

## Build Custom Functions with Code Components

The code component allows you to execute product or industry-specific code within an integration.
This page outlines when and how to use a code component.

## Why use a code component?

You will likely have integration logic that can't be solved using the [standard components](/docs/composer/builder/builder-components/epcc) we provide.
The portion of your integrations that are specific to your product or industry can be accomplished using code component steps.

## Adding a code component to an integration

Within the integration designer, [add a step](/docs/composer/builder/integrations/building-integrations#adding-steps-to-integrations) to your integration.
Select the **Code** component, **Code Block** action.

You will be presented with a new code step in your integration, and you can click the "Edit" button to open the code editor:

![Code editor](/assets/code-step.png)

## Code structure

The code component provides a stub function by default.
Let's examine the structure of the code:

```javascript
module.exports = async ({ logger, configVars }, stepResults) => {
  return { data: null };
};
```

The code component requires you to export an asynchronous function.
The default code uses [arrow function notation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) to create an `async` function to return.

## Code component parameters

This function is provided a few parameters:

1. The first positional parameter, is comprised of several properties:
   - `logger` allows you to write out log lines.
   - `configVars` lets you access config variables (including connections).
   - `instanceState`, `crossFlowState`, `integrationState` and `executionState` gives you access to persisted state.
   - `stepId` is the ID of the current step being executed.
   - `executionId` is the ID of the current execution.
   - `webhookUrls` contains the URLs of the running instance's sibling flows.
   - `webhookApiKeys` contains the API keys of the running instance's sibling flows.
   - `invokeUrl` was the URL used to invoke the integration.
   - `instance` is an object containing an `id` and `name` of the running instance.
1. The second positional parameter, `stepResults`, is an object that contains output from previous steps of the integration.

### Logging

`context.logger` is an object that can be used for logging and debugging.
`context.logger` has four functions: `debug`, `info`, `warn`, and `error`.
For example:

```javascript
module.exports = async (context, stepResults) => {
  context.logger.info("Things are going great");
  context.logger.warn("Now less great...");
};

// or

module.exports = async ({ logger }, stepResults) => {
  logger.info("Hello World");
};
```

**Note**: Log lines are truncated after 4096 characters.

### Config variables

`context.configVars` provides the Code Component with access to all [config variables](/docs/composer/builder/integrations/building-integrations#config-variables-in-integrations), including connections, associated with the integration.

If you have a config variable named `Acme ERP Base URL`, for example, you could reference that config variable in a code step with `context.configVars["Config Variable Name"]` syntax:

```javascript
module.exports = async ({ configVars }, stepResults) => {
  const fuelApiUrl = `${configVars["Acme ERP Base URL"]}/fuel`;
  // ...
};
```

### Connections

[Connections](/docs/composer/builder/integrations/building-integrations#connection-config-variables) are a special type of config variable.
You can access the contents of a connection the same way that you would any other config variable.
In this example, suppose you have a connection config variable named `Acme ERP Connection` that contains two fields, `tenantId` and `apiKey`:

```javascript title="Destructuring a connection config variable"
module.exports = async ({ logger, configVars }, stepResults) => {
  const {
    fields: { tenantId, apiKey },
  } = configVars["Acme ERP Connection"];
  const result = await doAThing({ tenantId, apiKey });
  return { data: result };
};
```

## Referencing previous step outputs

Most steps of an integration return some sort of value.
An **HTTP - GET** action, for example, might return a JSON payload from a REST API.
An **Amazon S3 - Get Object** will return a binary file pulled from S3.

The code component can reference those outputs through the `stepResults` parameter.
`stepResults` is an object that contains results from all previous steps.

For example, if you have an **HTTP - GET** step named **Fetch Users List** that pulls down an array of users from `https://jsonplaceholder.typicode.com/users`, you can generate an array of email addresses with this code:

```javascript
module.exports = async (context, stepResults) => {
  const userArray = stepResults.fetchUsersList.results;
  const emailArray = userArray.map((user) => user.email);
  return { data: emailArray };
};
```

:::note 

Step results are often objects. Many components return objects that have multiple keys. So, you can reference `stepResults.myStepName.results.someKey`. It's rare for a component to return serialized JSON, so there's rarely need to `JSON.parse()` results from a previous step.
:::

### Previous steps names as variables

Since names of steps can include spaces and non-JavaScript-friendly characters, alphanumeric characters of step names are converted to camelCase.
So, a step named **Download JSON from API** would be converted to **downloadJsonFromApi**.

### Referencing integration trigger payload data

The integration trigger is simply another step that can have a unique name.
Suppose an integration is triggered by a webhook, the trigger is named `My Integration Trigger`, and the webhook is provided a payload `body.data` of `{"exampleKey": "exampleValue"}`.

![Reference integration trigger payload](/assets/trigger-payload.png)

That `exampleKey` would be accessible using `stepResults.myIntegrationTrigger` like so:

```javascript
module.exports = async ({ logger }, stepResults) => {
  const exampleKey =
    stepResults.myIntegrationTrigger.results.body.data.exampleKey;
  logger.info(`Received '${exampleKey}'`);
};
```

Using JavaScript destructuring, you can instead write this:

```javascript
module.exports = async (
  { logger },
  {
    myIntegrationTrigger: {
      results: {
        body: {
          data: { exampleKey },
        },
      },
    },
  }
) => {
  logger.info(`Received '${exampleKey}'`);
};
```

Notice the logged message in the testing pane

![Test runner step results](/assets/using-stepresults.png)

## Code component return values

The code component can optionally return a value for use by a subsequent step.
The return value can be an object, string, integer, etc., and will retain its type as the value is passed to the next step.

The return value is specified using the `data` key in the return object.

In this example we return a string with value `"https://ipinfo.io/ip"`:

```javascript
module.exports = async (context, stepResults) => {
  return { data: "https://ipinfo.io/ip" };
};
```

The output can be used as input for the next step by referencing `codeComponentStepName.results`.

![Use output for prior step for input to new step](/assets/return-values.png)

To see an example of returning more complex data structures, and a good example use case for a code component, see the [Using a Code Component to Transform Data](/docs/composer/builder/quickstarts/code-component/code-component-to-transform-data) quickstart.

### Returning binary data from a code component

Sometimes you'll want your code component to return binary data (like a rendered image or PDF).
To do that, return an object with a `data` property of type `Buffer` (a file buffer), and a `contentType` property of type `String` that contains the file's [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types):

```javascript
module.exports = async (context, stepResults) => {
  // ...
  const fileBuffer = SomePdfLibrary.generatePdf();
  return {
    data: fileBuffer,
    contentType: "application/pdf",
  };
};
```

To see an example use case for returning binary data from a code component, check out our Generate a PDF with a Code Component.

**For More Information**:
See **Using a Code Component to Transform Data**.

## Adding dependencies to a code component

If your code component depends on node modules from `npm`, dependencies will be dynamically imported from the [UNPKG CDN](https://unpkg.com/).
For example, if your code component reads:

```javascript
const fetch = require("node-fetch@2.6.1/lib/index.js");

module.exports = async (context, stepResults) => {
  const response = await fetch("https://jsonplaceholder.typicode.com/todos/1");
  const responseJson = await response.json();
  return { data: responseJson };
};
```

Then [node-fetch](https://unpkg.com/browse/node-fetch@2.6.1/lib/index.js) version 2.6.1 will be imported as a dependency.

You should specify specific known working versions of `npm` packages for your code component:

```javascript
const lodash = require("lodash@2.4.2");
const fetch = require("node-fetch@2.6.1/lib/index.js");
```

You can require any file from `npm` using `package[@version][/file]` syntax.
Note that with the `lodash` import above, no file was specified.
If no file is specified, the `main` file defined in the `npm` package's `package.json` is imported.
An explicit path was called out for the `node-fetch` import because the `node-fetch` package defaults to importing a browser version of the package, and we want a compiled server version instead.

:::caution

Dynamic imports may or may not work, depending on how the dependency maintainer compiled their package.
If the package has its own dependencies that are not compiled in, you may see errors in your code.

You might also see errors if the UNPKG CDN is unavailable for any amount of time.

Components have their dependencies compiled in, and are not dependent on the uptime of an external CDN.
:::

---

## Code Components

Builder offers a wide array of built-in components to accomplish a variety of things, like serializing data formats, invoking REST endpoints, or interacting with commonly-used SaaS platforms like AWS, Slack, or Dropbox. The majority of your integrations can likely be developed using these standard components.

For the portions of your integrations that are specific to your industry or product, we provide the ability to run custom code as part of your integration.
You can deploy your own code with short code component steps.

## The code component

The code component is used for smaller, integration-specific proprietary code.
If a problem cannot be solved with built-in components, but can be solved with a few lines of JavaScript, the code component is a good choice for you.

---

## Components

A **component** is a portion of reusable code that accomplishes a specific task, or connects with an outside service.
For example, the SFTP component allows integrations to download and modify files on an SFTP server.
The Slack component posts messages to Slack channels.

Several components are strung together to form an [integration](/docs/composer/builder/integrations/overview).
A very simple integration might use the Amazon S3 component to pull down a file from S3, and post the contents of the file to a Slack channel using the Slack component.

![Simple integration](/assets/simple-sample-integration.png)

Complex integrations might be comprised of dozens of actions.

### Builder-provided components

Builder offers a wide array of components to accomplish a variety of things, like serializing data formats, invoking REST endpoints, or interacting with commonly-used SaaS platforms like AWS, Slack, or Dropbox - see our [component catalog](/docs/composer/builder/builder-components/epcc) for a full list of components.
Source code for some Builder-provided components is available on [GitHub](https://github.com/prismatic-io/examples/tree/main/components).

## Component actions

Components contain one or more **actions** that can be invoked.
For example, the Amazon S3 component contains actions to copy S3 objects, delete objects, get an object's contents, etc.

## Component authorization methods

Some components require credentials to interact with a SaaS provider, REST endpoint, etc.
Those credentials might be username/password sets, API keys, OAuth2 tokens, etc.

## Component connections

A **connection** is the mechanism by which a component authenticates with a third-party app or service.
A connection is an input and might contain a username/password set, API key, OAuth 2.0 token, or some other proprietary authentication type.

Component developers define the fields that make up a connection.
For example, a connection for one component might require a tenant ID and API key.
The single config variable representing that connection would be made up of two fields: one for tenant ID and one for API key.

**For More Information**:
[Configuration-Driven Integration Quickstart](/docs/composer/builder/quickstarts/integrations/configuration-driven-integration)

## Component versioning

Components are versioned. The first time a component is published it is given version "1". Thereafter, each time the component is republished its version number increments by one.

Versions of components used in integrations are not bumped to the latest version automatically. This prevents unintended issues in your integration if your team member were to publish a broken custom component. You can keep an integration pinned to component "version 6" for example, while your team members experiment with a newer "version 7" of a custom component for another integration.

To upgrade those components, click the **Component Versions** button and select **CHANGE VERSION** for the component whose version you want to change.

**For More Information**:
[Choosing Component Versions](/docs/composer/builder/integrations/building-integrations#choosing-component-versions)

---

## Build Your First Integration

This tutorial walks you through some basic concepts of integration development. You will:

- Fetch data from Commerce.
- Learn how data flows between steps of an integration.
- Send the data to another third-party.

## Integration Overview

The integration you build here retrieves an access token to grant you access to the Commerce API, verifies the access token, and logs the results.  

## Prerequisites

### Gather  Elastic Path Composable Commerce Data

You will need to create a connection using Elastic Path keys and authorization URL. See [Application Keys](/docs/authentication/security#application-keys). You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. 

| Option | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | This is the API URL. |
| **Client ID**                       | Your Store's Client ID. |
| **Client Secret**                   | Your Store's Client Secret. |

## Create a New Integration

1. In Commerce Manager, go to **COMPOSER** > **Builder**.
1. Select **+ Add integration**. The **Configure new integration** page displays.
1. From **Create new integration**, select **Quickstart** > **Build an integration from the ground up**. The **Details** page is displayed.
1. From **Create new integration** details page, provide the  **Name**,  enter  a  name  **My  First  Integration**  for  your  integration.
1. select **Webhook** for the trigger and click **Create trigger**.
    
## Review the Integration Trigger

Most integrations are either scheduled events or webhooks triggered by an Elastic Path [observable event](/docs/api/integrations/integrations-introduction#observable-events). For this tutorial, we are using the **Webhook Trigger**.

To see the  details  of  the  webhook  step,  click  the **Trigger** step  tile  to  display  the  drawer  details.  By  default,  the  following  settings  are  set:

1. **Response Type** is set to **Asynchronous**.
1. You can optionally set **Response Status Code** to **200 OK**.
1. You can optionally set **Response Content Type** to **application/json**.

## Add Your First Step

1. Click **+** under the **Webhook** step to add a new step. 
1. From **Add a step**, select the **Code** component. The **Code** component displays.
1. Select the **Code Block** action. Author and run your own code action. The **Code Block** action is added to the flow.
1. Click the step tile to display the drawer details.
1. Select the **Details** tab in the details drawer and enter  a  name  for  the  step,  for  example,  **Get  EPCC  Client  Token**.
1. Click the **Configure** tab.
1. Click **Edit**, enter the following:

    ```json
        const params =  new  URLSearchParams();
        module.exports =  async  ({ logger, configVars }, stepResults)  =>  {
	        
	        let base_url = "{{paste the url collected in gather step above}}"
	        let client_id = "{{paste the client id collected in gather step above}}"
	        let client_secret = "{{paste the client secret collected in gather step above}}"
	    	params.append('client_id', client_id);
	        params.append('client_secret', client_secret);
	        params.append('grant_type',  'client_credentials');
	        var response =  await fetch(base_url +  '/oauth/access_token',
		       {method:  'POST',body: params});
	       
	        var data =  await response.json();
	       
	        return  { data };
            };
    ```

1. Click the **Check mark** on the upper right corner of the embedded development dialog.
1. Click **Save**.
1. To test your code, click **Run** in the lower left to trigger manual execution of your integration.  It should say **Running** until each step completed.
1. Select the **Get  EPCC  Client  Token** step in the **Steps** panel to see the results of the code in the right **Output** panel. 

This example takes static code and executes a POST to the Commerce API and retrieves the access token and makes that JSON response available to subsequent steps.

## (Optional) Get External Data

The following steps will generate a number between 1 and 325, and retrieve the details of that Beer from **Sample APIs** open API, and and log the data.

1. Click  **+**  under  **Success**  Log message step  to  add  a  step  to  generate a random number between 1 and 325.  
1. Type **Math** in the search box and select the **Math** component.
1. Search for **Random** in the actions search box and select  Random Integer.
1. In the Min input box type **1** and in the Max input box type **325**.
1. Click the **+** under "Random Integer" and search for **HTTP**.
1. Select the **HTTP** component and then choose **Get Request**.
1. Click In the **URL** box, click the **Template** tab and type **https://api.sampleapis.com/beers/stouts/**.
1. To the right of the input box, click the **+** symbol to add a template field. 
1. Click the **Reference** tab. 
    
    The **Reference Step** should be **Random Integer**, and then in **Value Preview** double click the word **results**. 
1. Finally, click the **+** below the **Get Request** step, search for **Log** message again, and choose **Write Message** and for the "Log Message" click the **Reference** tab again and select the **results** of the **Get Request** step.

## Test Your Integration

Click **Save** in the upper right corner and then **Run** in the lower left once save has completed. This will open the **Test  History** dialog and show the results of the integration test.

---

## Prepare Your First Integration

In this tutorial, you'll prepare your integration for Integrations Hub. Once the integration is added, you can use it. An overview of these steps are:

1. Add a logo.
1. Add the integration to a category. 
1. Add the integration to the Integrations Hub.

## Add a Logo

To identify your integrations in Integrations Hub, add a logo.

1. Save a local copy of your third-party app's logo. 
1. In Builder, open your integration.
1. Next to **My First Integration**, select the image icon.
1. Browse to the location of the logo you saved in step 1.
1. Select **Open** to assign the logo to the integration.

## Assign a Category 

To help you filter and find your integrations quickly and easily, you can define categories for your integrations.

1. In Builder, open your integration.
1. In your integration, expand **Details**.
1. In **Category**, enter a category. If you do not enter a category, your integration is displayed in **Uncategorized**.
1. In **Description**, give a brief description of this integration.
1. Select **Details** again to close the dialog.

## Add your Integration to the Integrations Hub

1. Select **Marketplace Configuration**. The **Marketplace Configuration** page displays.
1. Select **Add to Marketplace**. 
1. If you want this integration to be available for use, turn the **Deployable** toggle on.
1. In **Overview** enter a brief description for this integration.
1. Select **Add**.
1. Close the **Marketplace Configuration** window to return to your integration.
1. Select **Publish** or **Update**, depending on whether you have already published this integration. 

You can now activate your integration in Integrations Hub.

---

## Building Integrations

After [creating a new integration](/docs/composer/builder/integrations/overview#creating-a-new-integration) or selecting one from your list of integrations, you can build, test, and publish integrations.

Builder contains four important features:

1. The configuration drawer lets you configure steps of your integration, change runtime/webhook configuration, etc.
1. The testing drawer lets you [run tests of your integration](/docs/composer/builder/integrations/testing-integrations), supply your integration with sample payloads, and see results of your integration test runs.
1. The version history drawer lets you publish a version of your integration, so it can be deployed to Integrations Hub.
1. The majority of the page is taken up by the integration editor pane.
   Here, you can add steps to your integration, create branches and loops, and generally arrange the flow of your integration.
   You can also create multiple **flows** - each flow has a [trigger](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers) and series of steps to be executed.

![integration designer highlighting configuration drawer, testing drawer, version history drawer, and integration editor pane](/assets/integration-designer.png)

## Integration steps

Actions, like downloading a file from an SFTP server or posting a message to Slack, are added as **steps** of an integration.
Steps are executed in order, and outputs from one step can be used as inputs for subsequent steps.

Steps are run in order from top to bottom, and you can add conditional logic to your integration with a [branch](#branching), or run a series of steps on a data set in a [loop](#looping).
If one step throws an error, the integration stops running.

### The trigger step

The first step of your integration is the **trigger** step, which determines when instances of your integration will run. [Integration triggers](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers) describes how triggers work, and how to invoke your integration.

### Adding steps to integrations

To add a step to an integration, click **+**  underneath the trigger or another action.

Select the component and action you would like to add to your integration.
For example, you can choose the **Amazon DynamoDB** component, and then select the **Create Item** action.
You can begin to type the name of the component or action you would like to add to filter the list of components and actions available.

![Choose component or action to add step](/assets/add-step.png)

### Cloning steps

If you would like to make a copy of a step in your integration, open the step's configuration drawer by clicking on the step, and then select the **clone step** button.

![Clone a step](/assets/clone-step.png)

This will copy the step, including any inputs you've configured for the action.

### Changing step actions

If you would like to change the action that a step uses, open the step's configuration drawer by clicking on the step and then select the **change step** button.

![Change a step's action](/assets/change-step-action.png)

You will be prompted to select a different action, and then will be prompted to fill in that new action's inputs.

### Step outputs

When a step runs, it optionally outputs data that can be used as input for subsequent steps.
For example, an SFTP **List Files** step will output an array of file names:

![Example of step outputs as a list](/assets/step-output-0.png)

An SFTP **Get File** step will output the contents of a file that it fetched from an SFTP server (in this case, an image):

![Example of step outputs as a file](/assets/step-output-1.png)

Outputs take one of three forms:

- A primitive value, like a **string**, **boolean value**, **number**, or **array** of primitives.
  A subsequent step that references this output will receive the string, boolean, number, or array as input.
- An **object**.
  An output might include multiple key-value pairs:

  ```json
  { "key1": "value1", "key2": ["value2.0", "value2.1", "value2.2"] }
  ```

  You might see this after pulling JSON from an HTTP endpoint.
  Specific values from an object can be referenced as inputs using familiar JavaScript `.dot` and `["bracket"]` notation.
  Using the above as an example, if you wanted to access `value2.1` you could reference `results.key2[1]`.

- A **binary file**.
  Binary file outputs contain a combination of a file `Buffer` and in indicator of content type (like `"image/png"`) in the form:

  ```json
  {
    "data": Buffer,
    "contentType": String
  }
  ```

:::note 
An action can return a combination of JSON and binary file(s) if properties of the JSON object are objects with `data` and `contentType` properties.
:::

### Configuring step inputs

Once you have added a step to your integration, you will likely need to configure some inputs for that step.
Inputs might include a RESTful URL endpoint, an S3 bucket name, a Slack webhook to invoke, or even a binary file like an image or PDF to upload or process.

Some inputs are required, and denoted with a `*` symbol, while others are optional.

Inputs can take one of four forms: **value**, **reference**, **config variable** or **template**.
**Value** inputs are static strings, **reference** inputs reference the results of a previous step, **config variable** inputs reference a customer-specific config variable, and **template** inputs allow you to concatenate static strings, config variables, and step result references.

#### Value inputs

A **value** is a simple string (perhaps a URL for an HTTP request).
If you set a **value** for an input, that static value is used as an input for all of your instances:

![Set input value](/assets/component-input-value.png)

#### Reference inputs

A **reference** is a reference to the output of a previous step.
For example, if a previous step pulls down a file from Amazon S3 and the step is named **Fetch my file**, then you can reference **Fetch my file** as an input for another step, and that subsequent step will be passed the file that **Fetch my file** returned.

Outputs from one step can be referenced by a subsequent step by referencing the previous step's **results** field.
So, if a previous step returned an object - for example, if an **HTTP - GET** action pulled down some JSON reading `{ "firstkey": "firstvalue", "secondkey": "secondvalue" }` - you access that `secondvalue` property in a subsequent step's input by selecting the **HTTP - GET** step and choosing `results.secondkey` in your **Reference search**:

![Reference earlier step result as step input](/assets/component-input-reference.png)

#### Config variable inputs

A **config variable** references one of the integration's config variables.
For example, we can select a config variable, `CMS API Endpoint`, as an input for one of our steps.
Config variables can be distinct for each customer, so each customer can be configured with a different `CMS API Endpoint`:

![Config variable inputs](/assets/component-input-config-var.png)

#### Templates inputs

Finally, a **template** is a combination of string values, config variables or step result references.
You can concatenate several strings, config variables, and step results together to serve as a single input.

Templates are useful if an input needs to be templated out from various config variables and step results.
For example, suppose you want to make an HTTP request to an API Endpoint that is stored as a config variable, and fetch an item whose ID was fetched in a previous step.
You could combine the API endpoint, URL path, and product ID like this:

![Add template input](/assets/template-input.png)

A static string, like `/product?id=` can be intermixed with config variables and step result references.

You can add references to config variables or step results by clicking the **ADD TEMPLATE FIELD** button.

![Template inputs](/assets/template-input-add-reference.png)

### Changing step names

By default steps are uniquely named after the action they invoke (so, they're named things like **CSV to YAML**, or **Delete Object**).
To override that default name, click the step and click the default name to edit its name.

Like using descriptive variable names in a program, renaming steps allows you to give your steps descriptive names.
For example, rather than a step being called **Delete Object** you can name it **Delete Schematics File from Share**.
We recommend giving your steps descriptive names so your team members can read through integrations and understand their purpose more readily.

If subsequent steps reference the renamed step's results as inputs, those references are automatically updated.
If you have code steps that reference the renamed step's results, you will see a prompt under the renamed step's name:

![Possible code change prompt](/assets/rename-step-code-diff-1.png)

If you click **View Options** you will find yourself in a diff tool that will recommend changes to your code, so references to the renamed step's outputs still work.
Make any changes you see fit, and click **Update** to apply the changes.

![Diff tool for code](/assets/rename-step-code-diff-2.png)

### Reordering steps

Steps are executed in serial.
To reorder steps, click and drag a step up or down.

![Reorder flow steps](/assets/reorder-steps.webp)

### Choosing component versions

Components are [versioned](/docs/composer/builder/components/overview#component-versioning).
You can choose a version of each component that works for your integration.
"Pinning" component versions for your integration prevents accidental regressions if a new version of a component is published that contains breaking changes.

To choose what version of each component your integration uses, click the **Component Versions** button on the right-hand side of the integration designer.

You can choose to run the latest version of a component, or any previous version.
Components running the latest available version will be marked in grey, while components running a version for which there is a newer version available will be marked in yellow.

![Component version list highlighting latest version](/assets/component-version-drawer.png)

To change the version of a component your integration uses, click the **CHANGE VERSION** button to the right of the component you want to change, and select a version from the dropdown.

**For More Information**:
[Component Versioning](/docs/composer/builder/components/overview#component-versioning)

## Step error handling

Sometimes a step in an integration throws an error.
This can be caused by a variety of external factors - temporary network connectivity issues, brief third-party API outages, etc.
You might not want your entire integration to stop because one step failed, especially if you're looping over hundreds of items and one item has issues.

You can configure how the integration runner should handle errors on each step.
To do that, click a step that you would like to configure, and then open the **Error Handling** tab in the left-hand drawer.

Under **Error Handler Type** you have three options:

- **Fail** - stop the integration and throw an error.
- **Ignore** - ignore the error and continue running the rest of the flow.
- **Retry** - wait for an amount of time (**Seconds Between Attempts**) and then try the step again, a maximum of **Max Attempts** times. Optionally wait longer and longer (**Exponential Backoff**, twice as long each time) between retries. If the last attempt still fails, either fail the integration or ignore the error depending on if **Ignore Final Error** is true or false.

![Screenshot of step-level error handling configuration](/assets/step-level-error-handling.png)

### Branching after ignored errors

If a step is configured to **Ignore** errors, or if the step has retried its configured number of times and then ignored the final error, the step returns a result with an `error` property detailing the error that occurred.
You can use the branch component to branch based on that error.

This is useful if you have some sort of [dead letter queue](https://en.wikipedia.org/wiki/Dead_letter_queue) to write the failed item to, or if you would like to notify someone of the problematic item.
You can branch on whether or not `results.error` **exists**, and act accordingly.

![Screenshot of branching on step-level error handling](/assets/branch-on-step-error.png)

## Config variables in integrations

When your users configure and activate an instance of your integration, they'll walk through an instance configuration wizard where they'll enter credentials, selection options from dropdown menus, map fields, toggle boolean values, etc.
Your integration can reference the config variables that users will set, and as an integration builder you can customize the configuration wizard experience for creating instances.

Start by opening the **Configuration Wizard Designer** by clicking the **Configuration Wizard** button.
From there, you can define the configuration experience that will be used.

### Configuration wizard designer

Users will enable and configure an instance of an integration through a **Configuration Wizard**.
Users work through **Configuration Pages**, authenticating with third-party apps and setting config variables.

**Configuration pages** can contain config variables of various types and helper text and images to prompt the user where to look.

![Screenshot of the configuration wizard designer](/assets/configuration-wizard-designer.png)

To add **helper text**, including headings (H1 - H6) or paragraphs, click the **+ Text/Image** button and select the type of text you'd like to add.

To add an **image**, your image will need to be publicly accessible online.
Enter the public URL of the image you'd like shown on your config page.

For further customization, you can choose to add **Raw HTML** to your config page.

You an add a configuration page by clicking **+ Config Page**, and you can rename a config page or add a short description to the page by clicking the pencil icon beside the page.

### Adding configuration variables

You can define names, descriptions, variable types, and optional default values of config variables to your configuration wizard, and you'll reference the values that users set for each in your integration.

![Config variables drawer](/assets/integration-config-vars.png)

When it comes time to deploy your integration, users can enter or select configuration options and tailor the integration without the involvement of integration builders.

Config variables that you define in the config variable drawer can be used within your integration as inputs or steps, or through the Branch component to drive branching logic.

### Config variable data types

There are several types of configuration variables:

- **String** is a standard string of characters
- **Date** follows the form `mm/dd/yyyy`, and presents end users a calender widget to choose a date
- **Timestamp** follows the form `mm/dd/yyy, HH:MM [AM/PM]`, and presents end users a calendar and time widget to choose a date and time
- **Picklist** allows you to define a series of options that your end user can choose from.
  Picklists are presented to end users as a dropdown menu of options.
  A picklist value can be up to 64 characters in length.
- **Code** lets your end user enter JSON, XML, or other formatted code blocks.
  Choose a Code Language when you create the config variable for syntax highlighting.
- **Boolean** allows your end user to choose either true or false.
- **Number** allows your end user to enter a number (integer or decimal).
- **Object Selection** allows your end user to select zero or more objects from a list.
  This config variable type always sources data from a [data source](#config-variable-data-sources).
- **Object Field Map** allows your end user to map a series of fields.
  This config variable type always sources data from a [data source](#config-variable-data-sources).
- **JSON Form** allows you to leverage [JSON Forms](https://jsonforms.io/) to build your users' configuration experience.
- **Connection** is made up of multiple fields that determine how a component should connect to an external API.
  It might include a username, password, API key, endpoint URL, or several other things.
  Note that connection config variables can only be added to the first config page, as subsequent pages may use the connection to dynamically generate other config variables.

The type of config variable you choose affects the UI that the end user interacts with (they get toggles for booleans, date pickers for timestamps, an editor with syntax highlighting for code, etc).
Regardless of what type of config variable you choose, though, all values are presented to actions as strings.

Once you've added a config variable, you can use it as an inputs to actions within your integration.

### List and key/value list config variables

In addition to representing a **single** value, some config var types can represent a **list** of values, or a list of **key/value pairs**.
This is helpful for when you want your users to be able to enter an unknown number of items as the values of a configuration variable.
For example, you may want users to select one or more values from a **picklist** menu.

Config variables with a data type of **string**, **date**, **timestamp**, **picklist**, **code**, or **boolean** can be configured as lists or key/value lists.

To create a **list** config variable, create a new config variable and select **LIST** under **Config Var Type**:

![Create list config variable](/assets/list-config-variable.png)

When a list config variable is referenced by a step's input, that step's action receives a JavaScript array of values.
The config variable in the example above would provide the array `["First Option", "Third Option", "Second Option"]` to the action.

To create a **key/value list** config variable, create a new config variable and select **KEY/VALUE LIST** under **Config Var Type**:

![Create key/value list config variable](/assets/key-value-list-config-variable.png)

When a key/value list config variable is referenced by a step's input, that step's action receives a JavaScript array of key/value pairs.
The config variable in the example above would provide this array to the action:

```javascript
[
  {
    key: "some-key",
    value: "Some value",
  },
  {
    key: "another-key",
    value: "Another value",
  },
];
```

### Config variable data sources

**Data Sources** allow you to populate a config variable dynamically after they enter some connection settings.
This is handy because users' configuration differs in third-party apps.
Users can have different Facebook business names, different Google Analytics accounts, different fields on Salesforce resources, etc.
You can pull in those things, and allow users to choose their Slack channel, select a folder in Google Drive, map fields from Salesforce, etc.

If you would like to populate a config variable dynamically from a data source, first ensure that a **connection** config variable for the third-party app is present on your first config page.
Those are generally automatically created when you add a step to your integration for that third-party.
On a subsequent page, add your config variable.
Under **Data Source**, select the component and data source that you would like to use (for example, the Salesforce component Map Record Type Fields data source.

Your users will authenticate with the third-party app on their first config page, and will see data dynamically loaded from the third-party populate the config variable.

### JSON Forms config variables

[JSON Forms](https://jsonforms.io/) is a powerful form-generating tool that lets you transform JSON schema into a fillable form.
You can build a static JSON form using the built-in JSON Forms component.

### Connection config variables

Connections are a special type of config variable that contain the information necessary to connect to a third-party app.
A connection might include a simple username and password pair, or might declare all the fields required for OAuth 2.0 (like auth URL, client ID, etc.).

Once a connection config variable has been created, it can be assigned to any number of steps in your integration that support that connection type.
For example, you can create a single Dropbox OAuth 2.0 connection, and assign that connection to a "List Files" step, "Get File" step and a "Delete File" step by selecting the connection from the connection input:

![Assign connection config variable to flow step](/assets/assign-connection-config-variable.png)

:::note
Connection config variables can only be added to the first page of the configuration wizard. This is because the connection can be used to dynamically populate config variables on subsequent pages.
:::

### OAuth 2.0 Connection Config Variables

A developer of a component that implements an OAuth 2.0 connection can choose to reveal or hide the various fields that are required for OAuth 2.0.
The required fields include auth URL, token URL, scopes, client ID, and client secret, but some of those fields never change, so they can be hidden from users.

For example, Dropbox auth URL and token URL never change, and scopes are set within Dropbox.
Only client ID and client secret are OAuth app specific.
So, when you create an OAuth 2.0 connection for Dropbox, only App Key (client ID) and App Secret (client secret) are revealed.

![Set visibility for connection field values](/assets/connection-field-visibility.png)

You as the integration builder can choose to enter static values for client ID and client secret at this point, or you can choose to let whoever deploys the integration enter those values.
You can manage who sees what by toggling the **Visible to Organization Deployer** toggle.

## Synchronous / asynchronous

Integrations can be triggered synchronously or asynchronously.
For more information, see [integration triggers](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#synchronous-and-asynchronous-integrations).

## Integration retry configuration

You can configure your [asynchronously](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#synchronous-and-asynchronous-integrations)-invoked instances to retry if they fail to run to completion.
This is handy if your integration relies on a flaky third-party API - the third party API might be down briefly, but back up a few minutes later.
You can configure your integration to try again in a few minutes when the API is back up, without needing to trigger unnecessary alert monitors for your team.

To configure an integration to retry its execution, click your trigger, and then **Flow Retry**.

![Set integration to retry](/assets/configure-retry.png)

**Retry Attempts** indicates the maximum number of times (up to 5) that Builder will run the same instance invocation in the event of failure.
If an instance has failed more than **Retry Attempts** number of times, the run will be marked as _execution failed_ and relevant alert monitors, if configured, will fire.

**Minutes Between Attempts** indicates the number of minutes that Builder should wait before trying to run an instance again.
If, for example, you specify **4** minutes, and the first instance invocation failed at 10:24, then the instance will attempt to run again at 10:28, 10:32, 10:36, 10:40 and 10:44 if it repeatedly fails to complete.

*Note*: Due to the nature of scheduled AWS Lambda functions, scheduled retries are precise to the minute (as opposed to to the second).
So, an attempt that fails at 10:24 with a **Minutes Between Attempts** set to 4 might trigger next at 10:28 or 10:29.

If you have **Exponential Backoff** selected, your instance will wait a longer and longer time between attempted runs, using an exponential factor of 2.
For example, if your **Minutes Between Attempts** is set to 3 and **Exponential Backoff** is set, then retry attempts will fire after 3, 6, 12, 24, and 48 minutes.

*Note*: The maximum amount of time an instance will take before retrying is **24 hours**.
If backoff is computed to wait more than 24 hours, it'll fire after waiting 24 hours instead.

Finally, **Retry Cancellation** gives you the ability to cancel a set of retry attempts if a more recent invocation of the instance has occurred.
For example, if your integration takes a payload as part of its invocation and then updates some third party system with that payload data, you may want to cancel older invocations if newer data comes in.
Otherwise, you may end up updating some third party system with newer data, and then the retry would overwrite the newer data with older data afterwards.

To configure retry cancellation, select a unique request ID from the trigger payload.
For example, you might pass in a header, `x-my-unique-id: abc123` as part of your trigger payload.
If another invocation with that header comes in that updates resource `abc123`, you might want to cancel currently queued retries.
To do that, select your trigger's `results.headers.results.headers.x-my-unique-id` reference as your **Unique Cancellation ID**.

Cancellation IDs do not need to be headers.
Instead, you can select a key from the payload body.
For example, if your instance invocation looks like this:

```json
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
  --location \
  --header "Content-Type: application/json" \
  --data '{"productId":"abc123","price":"250","description":"A box of widgets"}'
```

You can key your unique cancellation ID off of `results.body.data.productId`.

## Looping

For many integrations it's handy to be able to loop over an array of items, or to loop a certain number of times.
If your integration processes files on an SFTP server, for example, you might want to loop over an array of files on the server.
If your integration sends alerts to users, you might want to loop over an array of users.

Builder provides the loop component to allow you to loop over an array of items, or you can loop a predetermined number of times.
After adding a **loop** step to your integration, you can then add steps within the loop that will execute over and over again.

The **loop** components takes one input: a **items**.
**Items** is an array - an array of numbers, strings, objects, etc.
For example, one step might generate an array of files that your integration needs to process.
Its output might look like this:

```json
[
  "path/to/file1.txt",
  "path/to/file2.txt",
  "path/to/file3.txt",
  "path/to/file4.txt"
]
```

The loop component can then be configured to loop over those files by referencing the `results` of the **list files** step:

![integration designer highlighting configuration drawer, testing drawer, version history drawer, and integration editor pane](/assets/loop.png)

Subsequent steps can reference the loop step's `currentItem` and `index` parameters to get values like `path/to/file3.txt` and `2` respectively:

![Loop over items to get file paths](/assets/loop-current-item.png)

**For More Information**:
The Loop Component
Looping Over Files Quickstart
Looping Over a Paginated API

### Looping over lists of objects

The list of objects passed into a loop component can be as simple or complex as you like.

In this example, if we have a loop named **Loop Over Users**, and the loop was presented **items** in the form:

```json
[
  {
    "name": "Bob Smith",
    "email": "bob.smith@example.com"
  },
  {
    "name": "Sally Smith",
    "email": "sally.smith@example.com"
  }
]
```

Then the loop will iterate twice - once for each object in the list, and we can write a code component that accesses the loop's `currentItem` and `index` values and sub-properties of `currentItem` like this:

```javascript
module.exports = async (
  { logger },
  { loopOverUsers: { currentItem, index } }
) => {
  logger.info(`User #${index + 1}: ${currentItem.name} - ${currentItem.email}`);
};
```

That will log lines like `User #1: Bob Smith - bob.smith@example.com`.

### Looping over a paginated API

Many third-party APIs limit the number of records you can fetch at once, and let you load a batch (or "page") of records at a time.
You may need to loop over an unknown number of pages of records in an integration.

You can accomplish that with a combination of two loops (one to loop over pages, and one to loop over records on each page) and a [break loop](/docs/composer/builder/quickstarts/integrations/looping-over-a-paginated-api) action that stops loading pages when there are no more left to load:

![Loop over paginated API](/assets/paginated-loop.png)

Please reference [this quickstart](/docs/composer/builder/quickstarts/integrations/looping-over-a-paginated-api) for an example of how to loop over a paginated API.

### Return values of loops

A loop will collect the results of the **last** step within the loop, and will save those results as an array.
For example, if the loop is presented the list of JSON-formatted user objects [above](#looping-over-lists-of-objects), and the last step in the loop is a code component reading:

```javascript
module.exports = async(context, loopOverUsers: { currentItem }) => {
    return {data: `Processed ${currentItem.email}`}
}
```

Then the `result` of the loop will yield:

```json
["Processed bob.smith@example.com", "Processed sally.smith@example.com"]
```

## Branching

The branch component allows you to add branching logic to your integration.
Think of **branches** as logical paths that your integration can take.
Given some information about config variables or step results, your integration can follow one of many paths.

Branch actions are handy when you need to conditionally execute some steps.
Here are a couple of examples of things you can accomplish with branching:

**Example 1:** The webhook request your integration receives could contain an "Order Created", "Order Updated" or "Order Deleted" payload.
You need to branch accordingly.

**Example 2:** Your users want to be alerted when rocket fuel level is below a certain threshold.
You can branch into "send an alert" and "fuel level is okay" branches depending on results of a "check rocket fuel level" step.

**Example 3:** You want to [upsert](<https://en.wikipedia.org/wiki/Merge_(SQL)>) data into a system that doesn't support upserting.
You can check if a record exists, and branch into "add a new record" or "update the existing record" branches depending on if the record exists.

**For More Information**:
The Branch Component

### Branching on a value

Adding a Branch on Value action to your integration allows you to create a set of branches based on the value of some particular variable.
It's very similar to the switch/case construct present in many programming languages.

Consider **Example 1** above.
Suppose the webhook request you receive has a header, `payload-type` that can be one of three values: `order-create`, `order-update` or `order-delete`.
You can look at that value and branch accordingly.

![Branch on value](/assets/branch-on-value.png)

**For More Information**:
Branch on Value Action

### Branching on an expression

The Branch on Expression action allows you to create branches within your integration based on more complex inputs.
You can compare values, like config variables, step results, or static values, and follow a branch based on the results of the comparisons.

Consider **Example 2** above.
You have a step that checks rocket fuel level, and you want to alert users in different ways if their fuel levels are low.
You can express this problem with some pseudocode:

```python
if fuelLevel < 50:
    sendAnSMS()
else if fuelLevel < 100:
    sendAnEmail()
else:
    doNothing()
```

To express this pseudocode in an integration, add a step that looks up rocket fuel level.
Then, add a **Branch on an Expression** action to your integration.

Create one branch named **Fuel Critical**, and under **Condition Inputs** check that `results` of the fuel level check step **is less than** 50.
Then, create another branch named **Fuel warning** and check that `results` of the fuel level check step **is less than 100**.

This will generate a branching step that will execute the branch **Send Alert SMS** if fuel levels are less than 50, **Send Warning Email** if fuel levels are less than 100, or will follow the **Else** branch if fuel levels are 100 or above.

![Branch on expression](/assets/branch-on-expression.png)

### Branch on expression operators

You can compare config variables, results from previous steps, or static values to one another using a variety of comparison operators.
These operators each evaluate to `true` or `false`, and can be chained together with **And** and **Or** clauses.

- The **equal** operator evaluates if two fields are equal to one another, regardless of type.

  | Left Field      | Right Field     | Result  | Comments                                                       |
  | --------------- | --------------- | :-----: | -------------------------------------------------------------- |
  | `5.2`           | `5.2`           | `true`  |                                                                |
  | `5.2`           | `5`             | `false` |                                                                |
  | `"5.2"`         | `5.2`           | `true`  | Strings are cast to numbers when compared to numbers           |
  | `"Hello"`       | `"Hello"`       | `true`  |                                                                |
  | `"Hello"`       | `"hello"`       | `false` | String comparison is case-sensitive                            |
  | `false`         | `0`             | `true`  | Boolean `false` evaluates to `0`, and `true` evaluates to `1`. |
  | `[1,2,3]`       | `[1,2,3]`       | `true`  | Arrays whose elements are the same are considered equal        |
  | `{"foo":"bar"}` | `{"foo":"bar"}` | `true`  | Objects with the same keys/values are equal                    |

- The **does not equal** operator evaluates if two fields are _not_ equal to one another, regardless of type.

  | Left Field | Right Field | Result |
  | ---------- | ----------- | :----: |
  | `5.3`      | `5.2`       |  true  |
  | `[1,2,3]`  | `[1,2,4]`   |  true  |

- The **is greater than** operator evaluates if the left field is greater than the right field, and is an implementation of the JavaScript [greater than operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Greater_than).

  | Left Field | Right Field | Result  | Comments                                                                       |
  | ---------- | ----------- | :-----: | ------------------------------------------------------------------------------ |
  | `5.2`      | `5.3`       | `false` |
  | `5.3`      | `5.3`       | `false` | The values are equal; one is not greater than the other                        |
  | `"5.3"`    | `5.2`       | `true`  | Strings are cast to numbers when compared to numbers                           |
  | `"Hello"`  | `"World"`   | `false` | Strings are compared alphabetically - `"Hello"` does not occur after `"World"` |
  | `"hello"`  | `"World"`   | `true`  | The ASCII value for `"h"` occurs [after](https://www.asciitable.com/) `"W"`    |
  | `true`     | `false`     | `true`  | `true` (1) is greater than `false` (0)                                         |

- The **is greater than or equal to** operator is similar to **is greater than**, but also returns true if the values being compared are equal to one another.

  | Left Field | Right Field | Result | Comments                                             |
  | ---------- | ----------- | :----: | ---------------------------------------------------- |
  | `5.3`      | `"5.3"`     | `true` | Strings are cast to numbers when compared to numbers |

- The **is less than** operator evaluates if the left field is less than the right field.

  | Left Field | Right Field | Result | Comments                                |
  | ---------- | ----------- | :----: | --------------------------------------- |
  | `3`        | `4`         | `true` |                                         |
  | `"abc"`    | `"daa"`     | `true` | `"a"` is less than `"d"` alphabetically |

- The **is less than or equal to** operator is similar to **is less than**, but also returns true if the values being compared are equal to one another.
- The **contained in** operator evaluates if the value of the left field is contained in the right field.
  The right field must be an array or a string.

  | Left Field | Right Field       | Result  | Comments                                                          |
  | ---------- | ----------------- | :-----: | ----------------------------------------------------------------- |
  | `"world"`  | `"Hello, world!"` | `true`  |                                                                   |
  | `"World"`  | `"Hello, world!"` | `false` | String comparison is case-sensitive                               |
  | `2`        | `[1,2,3]`         | `true`  |
  | `"2"`      | `[1,2,3]`         | `false` | The string `"2"` does not occur in the array of numbers `[1,2,3]` |

- The **not contained in** operator evaluates if the value of the left field does not appear in the right field.

  | Left Field | Right Field | Result  |
  | ---------- | ----------- | :-----: |
  | `2`        | `[1,2,3]`   | `false` |
  | `'Hi'`     | `'Hello'`   | `true`  |

- The **is empty** operator evaluates if the given value is an empty string or an empty array.

  | Field     | Result  |
  | --------- | :-----: |
  | `""`      | `true`  |
  | `"hello"` | `false` |
  | `[]`      | `true`  |
  | `[1,2,3]` | `false` |

- The **exactly matches** operator evaluates if the two fields are equal to one another, taking type of the values into consideration.

  | Left Field | Right Field | Result  | Comments                                        |
  | ---------- | ----------- | :-----: | ----------------------------------------------- |
  | `"5"`      | `5`         | `false` | The string `"5"` is not equal to the number `5` |

- The **does not exactly match** operator evaluates if the if the two fields are not equal to one another, taking type of the values into consideration.

  | Left Field | Right Field | Result | Comments                                        |
  | ---------- | ----------- | :----: | ----------------------------------------------- |
  | `"5"`      | `5`         | `true` | The string `"5"` is not equal to the number `5` |

- The **starts with** operator evaluates if the the right field's value begins with the left field's value.
  Both right and left values must be strings.

  | Left Field | Right Field         | Result  | Comments                                                       |
  | ---------- | ------------------- | :-----: | -------------------------------------------------------------- |
  | `"Test"`   | `"Testing Value"`   | `true`  |                                                                |
  | `"test"`   | `"Testing Value"`   | `false` | Comparisons are case-sensitive                                 |
  | `"Test"`   | `"A Testing Value"` | `false` | The right field must start with (not _contain_) the left value |

- The **does not start with** operator returns the opposite of the **starts with** operator.
- The **ends with** operator evaluates if the right field ends with the left field.
  Both right and left values must be strings.

  | Left Field | Right Field     | Result  |
  | ---------- | --------------- | :-----: |
  | `orld!`    | `Hello, World!` | `true`  |
  | `orld`     | `Hello, World!` | `false` |

- The **does not end with** operator returns the opposite of the **ends with** operator.

    :::note
    The following three comparison operators accept date/times as strings in these three formats: `YYYY`, `YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ssZ[Z]`. Additionally, UNIX epoch timestamps in milliseconds are accepted (for example, the number `1631568050` represents a time in 2021-09-13).
    :::

- The **is after (date/time)** operator attempts to parse the left and right fields as dates, and evaluates if the left field occurs after the right field.

  | Left Field                   | Right Field                  | Result  | Comments                                                                          |
  | ---------------------------- | ---------------------------- | :-----: | --------------------------------------------------------------------------------- |
  | `"2021-03-20"`               | `"2021-04-13"`               | `false` |                                                                                   |
  | `"2021-03-20T12:50:30.105Z"` | `"2021-03-20T11:52:21.881Z"` | `true`  | When dates are equivalent, time is compared                                       |
  | `"2021-03-20"`               | `1631568050`                 | `false` | `1631568050` is the UNIX epoch time for 2021-09-13, which occurs after 2021-03-05 |

- The **is before (date/time)** operator attempts to parse the left and right fields as dates, and evaluates if the left field occurs before the right field.
- The **is the same (date/time)** operator attempts to parse the left and right fields as dates, and evaluates if the timestamps are identical.

  | Left Field                   | Right Field                  | Result  | Comments                                                                               |
  | ---------------------------- | ---------------------------- | :-----: | -------------------------------------------------------------------------------------- |
  | `"2021-03-20T12:50:30.105Z"` | `"2021-03-20T12:50:30.105Z"` | `true`  |
  | `"2021-03-20T12:50:30Z"`     | `1616244630000`              | `true`  | `1616244630` is the millisecond UNIX epoch representation of `March 20, 2021 12:50:30` |
  | `"2021-03-20T12:50:30Z"`     | `"2021-03-20T12:50:31Z"`     | `false` |

- The **is true** operator evaluates if an input field is "truthy".

  Common "truthy" values include `true`, `"true"`, `"True"`, `"Yes"`, `"yes"`, `"Y"` and `"y"`.

  Common "falsy" values include `false`, `"false"`, `"False"`, `"No"`, `"no"`, `"N"` and `"n"` and evaluate to `false`.
  Other values that evaluate to `false` are `0`, `null`, `undefined`, `NaN` and `""`.

  All other values (a non-zero number, a non-empty string, any array or object, etc.) evaluates to `true`.

  | Field     | Result  |
  | --------- | :-----: |
  | `"Yes"`   | `true`  |
  | `"True"`  | `true`  |
  | `[]`      | `true`  |
  | `{}`      | `true`  |
  | `"Hello"` | `true`  |
  | `-5`      | `true`  |
  | `"n"`     | `false` |
  | `false`   | `false` |
  | `""`      | `false` |
  | `null`    | `false` |
  | `0`       | `false` |

- The **is false** operator returns the opposite of the **is true** operator.
- The **does not exist** operator evaluates to `true` if the presented value is one of the following: `undefined`, `null`, `0`, `NaN`, `false` or `""`.

  | Field       | Result  |
  | ----------- | :-----: |
  | `undefined` | `true`  |
  | `NaN`       | `true`  |
  | `1`         | `false` |
  | `"Hello"`   | `false` |

- The **exists** operator returns the opposite of the `does not exist` operator.

### Combining multiple comparison operators

Multiple expressions can be grouped together with **And** or **Or** clauses, which execute like programming **and** and **or** clauses.
Take, for example, this programming expression:

```
if ((foo > 500 and bar <= 20) or ("b" in ["a","b","c"]))
```

The same logic can be represented with a group of conditionals in a Branch on Expression action:

![Branch on expression using conditionals](/assets/branch-on-expression-logic.png)

### Converging branches

Regardless of which branch is followed, branches always converge to a single point.
Once a branch has executed, the integration will continue with the next step listed below the branch convergence.

This presents a problem: how do steps below the convergence reference steps in branches that may or may not have executed (depending on which branch was followed)?
In your integration you may want to say "if branch _foo_ was executed, get the results from _step A_, and if branch _bar_ was executed, get the results instead from _step B_."
Builder provides the Select Executed Step Result to handle that scenario.

Imagine that you have two branches - one for incoming invoices, and one for outgoing invoices, with different logic contained in each.
Regardless of which branch was executed, you'd like to insert the resulting data into an ERP.
You can leverage the Select Executed Step Result action to say "get me the incoming or outgoing invoice - whichever one was executed."

This action iterates over the list of step results that you specify, and returns the first one that has a non-null value (which indicates that it ran).

![Select executed step result while branching](/assets/select-executed-step-result.png)

Within the component configuration drawer, select the step(s) whose results you would like, and the **Select Executed Step Result** step will yield the result of whichever one was executed.

## Persisting data between runs

Sometimes it's helpful to save data from one execution of an integration so it can be used in a subsequent execution.
Builder provides components that allow you to save some state from one run for use in a future run.

Why is this important or helpful?
Imagine you have an integration that pulls down and processes data from a data source.
Your integration recently processed a record with ID "123", and the next time your integration runs you want to ensure it processes ID "124" and above.
You can persist "123" using a Save Value action, and then the next time your integration runs it can use Get Value to know that "123" was the most recently processed record.
You can then build your integration to process newer records than the one that was saved.

Let's look at two components that take advantage of persisting data:

### The persist data component

Data can be persisted between runs using the Persist Data component.
Data are stored in key-value pairs, and values can be strings, numbers, objects, or lists.
You can choose to persist data with the `Flow -` actions - that lets you persist data scoped to the current flow.
You can also use the `Cross Flow -` actions to persist data that can be shared between flows of an instance.
Or, you can use the `Integration -` actions to persist data between instances of the same integration (so, multiple instances can share a data store).

You can store a key/value pair using the Save Value action, or you can use Persist Data's other actions to append to a persisted list.
If you would like to save a timestamp instead, you can use the Save Current Time action to save the current time into a key of your choosing.

Later, in a subsequent run, you can fetch the value you saved using the Get Value action.
If a key is not set, **Get Value** will return `null`.

You can remove data from an array, or remove a key/value pair altogether, using Persist Data's other actions.

### The process data component

For some integrations, it's handy to know what data from an array you've already processed, and what data you haven't.
For example, your integration might pull down an array of orders from a data store to be converted into invoices.
Your order array might look like this:

```json
[
  {
    "orderid": 123,
    "items": {
      "widgets": 5,
      "whatsits": 7
    }
  },
  {
    "orderid": 122,
    "items": {
      "whoseits": 2
    }
  }
]
```

The Process Data's DeDuplicate action allows you to pass in such an array objects in **descending order**, along with a unique identifier (like `orderid`).
The action uses data persistence between runs to track the most recently processed item (in this example, `"orderid": 123`).
The next time this integration is run and an array of orders are passed into the **DeDuplicate** step, the step will return all objects in the array that appear **before** the object with `"orderid": 123`.
So, if there's an order ID 124, 125, etc., it'll return those.
That way, the subsequent execution will ignore order ID 123 and before, and instead process only more recent orders.

## For More Information:
Persisting Data in Custom Components

## Flows in integrations

Some integrations have a single **flow** (a single trigger, and a series of steps that are executed).
If you have multiple logical flows that are related - for example, if you are integrating with Acme ERP, and Acme ERP is configured to send a variety of webhook payloads to you - you can combine multiple flows into a single integration, one flow to handle each webhook type.
Rather than deploying a dozen distinct instances to integrate with Acme ERP, it's more manageable to deploy a single integration that is made of multiple flows.

An integration's [config variables](#config-variables-in-integrations) are scoped for the integration.
So, a config variable set for an integration is shared and can be referenced by any of the integration's flows.
Each flow has its own unique trigger, and so has its own [webhook URL](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#webhook-triggers) that you can use to invoke that specific flow.

### Managing integration flows

To add a new flow to your integration click the **+ Add flow** button on the top of the designer.

![Manage integration flows](/assets/manage-flows.png)

To edit a flow, click your current flow's name and then click the pencil icon to the right of a flow.
Each flow should be given a unique name, and can have an optional description.

To delete a flow from an integration, click the trash icon to the right of the flow's name and description.

### Cloning a flow

If you need to add a flow that is similar to another flow you've already built, it's helpful to be able to **clone** (make a copy of) a flow.
To clone a flow, open the flow menu by clicking the name of your flow on the top left of the integration designer.
Then, select the **content_copy** icon, and give your copy a new name.

![Clone integration flow](/assets/clone-flow.png)

### Testing and running flows

Each flow runs separately and has its own trigger.
They're tested independently as well.
To test a flow, click the flow selection button on the top left of the integration designer area and select the flow you would like to test.
Then, run tests just as you would with a single-flow integration.

## Interacting with SOAP APIs

A **Simple Object Access Protocol** (SOAP) API defines how a client should interact with the API through XML and a schema called a WSDL.
To interact with a SOAP-based API, you can use the built-in generic SOAP component to fetch and interpret the WSDL and make requests to the API.

---

## Integration Runner Environment and Limits

## The Builder runner environment

Instances of integrations (and test runs of integrations) execute in isolated NodeJS containers with distinct filesystems and memory.
Two instances of the same integration run in distinct isolated environments.
Integrations currently run using NodeJS version 14.x.

## Runner limitations

### Memory allocation

The Builder integration runner is allocated 1GB of RAM for execution.

### Execution time limitations

An instance will run for up to 15 minutes.

## Webhook limitations

### Webhook request size limitations

Webhook payload size is limited to 6MB.
6MB is generally large enough to handle most JSON, XML, or other webhook payloads.

If the payload you need to process exceeds 6MB (i.e. you are processing large images, PDFs, etc.), we recommend saving the large file to a file storage system first (Dropbox, Amazon S3, Azure Files, etc.), and sending _metadata_ about the file in your webhook request.
Your integration can use the metadata to fetch the file for processing.

### Synchronous webhook response size limitations

When a webhook is invoked synchronously, the response contains the results of the last step of the flow (so, if the last step returned a PDF file, the webhook response would be a PDF file).
Builder writes response to a file in Amazon S3, and responds with an HTTP 303 (Redirect) to the object in S3.

Step results have a maximum size of 500MB.
If the results that you generate exceed 500MB, consider writing the file to a file storage system (Dropbox, your own Amazon S3 bucket, etc) and returning metadata about the file instead.

**Read More**: [Synchronous Invocations and Redirects](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#synchronous-and-asynchronous-integrations)

### Synchronous invocation timeouts

A webhook request will time out after 30 seconds.
Webhook requests to [synchronous triggers](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#synchronous-and-asynchronous-integrations) (triggers that wait until the execution finishes running before responding) must complete their work in under 30 seconds.

---

## Endpoint Configuration

Webhook triggers can be configured for an integration in one of two ways, depending on your needs:

- **Instance and Flow Specific**: Each flow on each instance gets its own unique endpoint. This is the default configuration.
- **Instance Specific**: Each instance gets a unique endpoint, and the integration determines which flow to run based on header or payload data.

When deciding on a webhook endpoint configuration, ask yourself two questions:

1. Do my webhook endpoints need to be the same for each of my instances, or can instances be configured to use different webhook endpoints?
1. If my instances can have unique webhook endpoints, can webhooks be configured to send data to unique endpoints depending on what activity they're responding to?
   For example, if a third-party app invokes an integration when it has an inventory update **or** when a new order is created, can those two activities be configured to invoke distinct webhook endpoints?

Once you have answers to those questions, you can choose the appropriate webhook endpoint configuration.

## Selecting endpoint configuration

To configure your integration's endpoint settings, click the **Endpoint Configuration** button on the right-hand side of Builder.
From the **Endpoint Type** input, select one of the three endpoint types listed above.

![Select endpoint type](/assets/select-endpoint-type.png)

Depending on what endpoint type you choose, you will be presented with different configuration options (described next).

## Instance and flow-specific endpoint configuration

This is the *default* configuration.
When an instance is deployed, each flow within the instance is assigned its own webhook endpoint.

Instance A's "Update Inventory" flow has a unique endpoint that is different than Instance A's "Process Order" flow endpoint, and different than Instance B's "Update Inventory" flow endpoint.

Integrations that use this endpoint configuration often set up webhooks with a [deploy trigger](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#instance-deploy-trigger), and remove them with an [instance remove](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#instance-remove-trigger) trigger.

## Instance-specific endpoint configuration

When an instance is deployed, that instance is assigned a single webhook endpoint.
The flows that comprise the instance all share that endpoint.
Each instance has a unique endpoint, so Instance A of the "Acme ERP" integration will have one endpoint, and Instance B of the same integration will have a different endpoint.

**If flows share an endpoint, which flow is executed?**
Since several flows share an endpoint URL, you need a way to determine which flow should run when data is sent to your endpoint.
You can determine which flow to run in two ways:

1. **Without a preprocess flow**. You can send the name of the flow that should run as an HTTP header or as a value in the HTTP payload.
1. **With a preprocess flow**. You can designate one flow of your integration to be a **preprocess** flow - that flow will determine which sibling flow should run.

### Instance-specific endpoint without a preprocess flow

If you do not use a preprocess flow, you can send the name of the flow to run as an HTTP header or as a value in the HTTP payload.

#### Flow name from HTTP payload

For example, you could send the name of the flow you'd like to execute as part of your payload like this:

```bash {2} title="Determine flow name from HTTP payload"
curl https://us-east-2.elasticpathintegrations.com/trigger/EXAMPLE== \
  --location \
  --header "Content-Type: application/json" \
  --data '{"myFlowName":"Update Inventory","item":"widgets","quantity":5,"state":"removed"}'
```

Within the **Endpoint Configuration** drawer, you could choose to reference `results.body.data.myFlowName` to determine which flow to run:

![Set flow name from HTTP payload for Endpoint Configuration](/assets/flow-name-from-payload.png)

Given the `curl` invocation above, the `Update Inventory` flow would be run with the rest of the payload that was provided.

:::tip
Run a test of endpoint configuration
In order to populate the result picker in the screenshot above, click **TEST RUNNER** and then open the **Endpoint** -> **Payload** tab.
Enter a sample payload and click **Save & Test Endpoint**.
Your test data will be available in the result picker menu in the **Endpoint Configuration** drawer.
:::

#### Flow name from HTTP header

If you'd like to pass flow name as an HTTP header instead, a `curl` invocation could look like this:

```bash {4} title="Determine flow name from an HTTP header"
curl https://us-east-2.elasticpathintegrations.com/trigger/EXAMPLE== \
  --location \
  --header "Content-Type: application/json" \
  --header "myflowname: Update Inventory" \
  --data '{"item":"widgets","quantity":5,"state":"removed"}'
```

In that case, you would reference `results.headers.myflowname` to determine which flow to run:

![Set flow name from HTTP payload for Endpoint Configuration](/assets/flow-name-from-payload.png)

:::caution 
Per [HTTP RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616#section-4.2), HTTP headers should be case-insensitive.
We've found HTTP clients to be inconsistent about their behavior and implementations, though.
[Postman](https://www.postman.com/), for example, will send camel-cased headers, while others will always lower-case header keys.

We recommend that you use lower-case HTTP header keys to avoid compatibility issues.
:::

### Instance-specific endpoint with a preprocess flow

If you need additional logic to determine which flow to run (for example, if you need to inspect an XML payload's shape to determine what kind of data was received), you can leverage a **preprocess flow**.
This flow executes when data is sent to the instance's endpoint.
It can be comprised of any number of steps, and the last step's results determine which sibling flow to execute.

To configure a preprocess flow, first build a flow that can inspect an incoming payload, and verify that the last step returns the name of the flow that you'd like to run next.
Then, open the **Endpoint Configuration** drawer, select your preprocess flow from the **Preprocess Flow** dropdown menu, and under **Flow Name** select the key representing the name of the flow that should run:

![Set flow name from preprocess flow for Endpoint Configuration](/assets/flow-name-from-preprocess-flow.png)

You may need to run a test of your preprocess flow in order to populate the result picker in the **Endpoint Configuration** drawer.

## Testing endpoint configuration

You can test each of your flows individually (including a **preprocess flow**, if applicable) by clicking the **SAVE & TEST FLOW** button on the top right of Builder.
If you would like to test your endpoint configuration, click the arrow icon to the right of **SAVE & TEST FLOW**, and toggle the dropdown to **Test Endpoint Configuration**.
Then, you can click **SAVE & TEST ENDPOINT** to test your endpoint configuration.

To configure a test payload, open the **TEST RUNNER** drawer, select the **Endpoint** tab, and then select the **Payload** tab.
You can enter the payload and any headers that you would like to send to the shared endpoint.

![Test endpoint configuration](/assets/test-endpoint-config-payload.png)

Within the **Logs** and **Step Outputs** tabs you will see logs and step results for both the preprocess flow (if you have one), and the flow that the request was routed to.

If an error is thrown (for example, the flow name that the preprocess flow generated was not found), that error will appear in the **Logs** tab.

:::note

Builder is a sandbox. No test invocations will go to your existing instances.

:::

## Troubleshooting shared endpoints in production

If you have an integration with [Instance-Specific Endpoint Configuration](#instance-specific-endpoint-configuration), then all logs and execution records will appear in the instance's execution results page.
Executions that that run through a [preprocess flow](#instance-specific-endpoint-with-a-preprocess-flow) that then trigger a sibling flow are packaged together as one execution in the executions page.
If your instance's preprocess flow throws an error or yields the name of a flow that doesn't exist, you can see those errors and step results from that page.

---

## How to Use Integration Triggers

Integration triggers allow you to define *when* an instance should run.
There are several types of triggers, with [schedule triggers](#scheduled-triggers) and [webhook triggers](#webhook-triggers) being the most commonly used.
Many components include triggers that do things like validate webhook payloads, preprocess data, or return custom responses to the webhook caller.
You can also configure a [deploy trigger](#instance-deploy-trigger) that runs when your integration is deployed to a customer.

- If you are integrating with a particular app or service, and that service has a component with a trigger, use that trigger.
- If you would like your integration to run on a predefined regular basis, you should use a schedule trigger.
- If you would like to invoke your integration from another system that can make HTTP calls, you should use a webhook trigger.
- If you have a flow that you would like to run when an instance is deployed, use a deploy trigger.

If your integration has multiple [flows](/docs/composer/builder/integrations/building-integrations#flows-in-integrations), each flow has its own trigger (and so its own webhook URL or schedule).

You can always change which trigger your flow uses by clicking on the trigger, and clicking the **CHANGE TRIGGER** button in the drawer that appears.

## Scheduled triggers

Scheduled triggers allow you to create a regular schedule to dictate how often your integration should run.
This is useful if you have an integration that should be triggered consistently at a specific time.
You can set up your integration to run at the same time for all customers, or you can set up schedules on a per-customer basis.

To set up the same schedule for all customers, click the integration's trigger, open the **Schedule** tab, and enter the schedule you would like your integration to follow.
You can configure your integration to run every X minutes, hours, days, or weeks:

![Set static integration trigger](/assets/static-schedule.png)

You can alternatively select **Custom** and provide a [cron string](https://en.wikipedia.org/wiki/Cron).
For example, a trigger of `*/5 8-16 * * 1-5` would cause your integration to run every five minutes during business hours (8:00-16:55), Monday through Friday.
For help computing a cron schedule, see this [Cron Calculator](https://crontab.guru/).

To configure schedules on a per-customer basis, first create a config variable of type **Schedule** by clicking the **Configuration Wizard** button.
You can give your config variable any name you choose:

![Configure integration trigger to use config variable](/assets/schedule-config-variable.png)

Then, click your integration trigger and reference the **Config Variable** you created:

![Set config variable for integration trigger](/assets/config-driven-schedule.png)

When your integration deployment team later deploys an instance of your integration, they can configure a custom schedule for that instance.

## Webhook triggers

Webhook triggers allow you to run a particular instance or [flow](/docs/composer/builder/integrations/building-integrations#flows-in-integrations) of an instance by making an HTTP POST, PUT, PATCH, DELETE or GET request to the webhook's URL.
This is useful if you would like an outside application to invoke an integration when something within the outside application occurs.
The outside application can assemble some data, and send that data to a Builder webhook URL via an HTTP request.

For example, third-party software could invoke an instance with a JSON payload whenever a job in the third-party application is complete, like this:

```bash
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
  --data '{"renderId":51266,"s3Bucket":"test-customer-renders","status":"complete"}' \
  --header "Content-Type: application/json"
```

Note that the payload of the request is available by referencing the integration's trigger, shown in the screenshot below.
Steps can then reference data from the webhook payload through the trigger's results.
Headers are available through `results.headers` and body data is available through `results.body.data`:

![Set webhook trigger via POST request](/assets/webhook-trigger-payload.png)

:::note 
The GET verb is supported
You _can_ use the GET verb to invoke an instance, but note that the GET verb does not allow you to send data with your request.
If you need to send data with your request, use the POST, PUT, DELETE or PATCH verbs.

The GET verb was introduced because some applications send a GET request when a webhook is configured to verify that the webhook endpoint is ready to receive requests.
:::

### Webhook trigger responses

By default, webhook triggers provide an HTTP code 200 ("OK") response to callers of the webhook.
The response body contains an execution ID, which can be used later to get logs and step results from the Prismatic API.
The response looks like this:

```bash
curl \
  --data '{}' \
  --header "Content-Type: application/json" \
  'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE=='

{"executionId":"SW5zdGFuY2VFeGVjdXRpb25SZXN1bHQ6OTdiNWQxYmEtZGUyZi00ZDY4LWIyMTgtMDFlZGMwMTQxNTM5"}
```

You can customize the response by clicking the integration webhook trigger and selecting a different HTTP code, response body, or response content type:

![Customize webhook trigger response code](/assets/webhook-trigger-response.png)

### Other webhook trigger responses

You may encounter other responses to your webhook trigger request.

#### HTTP 303 See Other / Redirect to S3 Results Bucket

When your webhook trigger is invoked [synchronously](#synchronous-and-asynchronous-integrations), your HTTP client sends a request and waits for the integration to finish running before closing the request.
Builder responds to the request with an HTTP 303 redirect, redirecting your HTTP client to an object in an Amazon S3 bucket that contains the results of the last step of your integration.

Ensure that your HTTP client follows redirects (for `curl`, you add a `--location` flag).

```txt title="Synchronous request redirected"
$ curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/example==' --location -v

...

< HTTP/2 303
< content-type: application/json
< content-length: 0
< location: https://example.s3.us-east-2.amazonaws.com/example
< date: Wed, 28 Sep 2022 19:42:24 GMT
< x-amzn-requestid: 4c2a5179-89a2-4351-afe0-336df2cdef11
< access-control-allow-headers: Accept,CloudFront-Forwarded-Proto,CloudFront-Is-Desktop-Viewer,CloudFront-Is-Mobile-Viewer,CloudFront-Is-SmartTV-Viewer,CloudFront-Is-Tablet-Viewer,CloudFront-Viewer-ASN,CloudFront-Viewer-Country,Host,User-Agent,Via,X-Amz-Cf-Id,X-Amzn-Trace-Id,X-Forwarded-For,X-Forwarded-Port,X-Forwarded-Proto
< x-amz-apigw-id: ZL6A7GegCYcF5Ew=
< prismatic-executionid: SW5zdGFuY2VFeGVjdXRpb25SZXN1bHQ6NGVjMTJiNWMtODk2ZC00ZGJiLThjZDgtZWUwYzNlMDE4OTBh
< access-control-allow-methods: GET
< x-amzn-trace-id: Root=1-6334a39f-0f975a9a7bb343c768645c36;Sampled=1
< x-cache: Miss from cloudfront
< via: 1.1 d67353af1bc95b93fa6102d888271954.cloudfront.net (CloudFront)
< x-amz-cf-pop: ORD58-P7
< x-amz-cf-id: xraa6hPBPc_texazIJXdKgavfwVRMW2oV85GqwCx6xUkUck7MxGKPg==
<

...

* Connection #0 to host hooks.us-east-2.elasticpathintegrations.com left intact
* Issue another request to this URL: 'https://example.s3.us-east-2.amazonaws.com/example'

...

< HTTP/1.1 200 OK
< x-amz-id-2: zx2ZHsGlC/Szu3HCp7xjRAVDALsEdQ/TJ5x/MkcbFkAB8DjLmRJOWCyTGmpI93UhdpqeYxt7hVo=
< x-amz-request-id: SE5KV3CJ5AXCYGZA
< Date: Wed, 28 Sep 2022 19:42:25 GMT
< Last-Modified: Wed, 28 Sep 2022 19:42:25 GMT
< x-amz-expiration: expiry-date="Sat, 29 Oct 2022 00:00:00 GMT", rule-id="expire-old-step-results"
< ETag: "083be81885a78809b54f4deead0e6c24"
< x-amz-server-side-encryption: AES256
< x-amz-version-id: 7bc_zpEQGmpc_stsaC.9vcF1DqxzXWx.
< Accept-Ranges: bytes
< Content-Type: application/octet-stream
< Server: AmazonS3
< Content-Length: 11
<
* Connection #1 to host payload-bucket20200616192411543900000009.s3.us-east-2.amazonaws.com left intact
{"item":"Widgets","quantity":5}
```

:::caution 
Combining `--location` and an explicit `--request POST` (or `-X POST`) flag in the same `curl` command can have unintended consequences.
`curl` will be redirected to an S3 bucket, but will attempt to make a `POST` request (rather than a `GET` request) to the S3 bucket.
This results in S3 responding with a `SignatureDoesNotMatch` error.

You will see the S3 error within [Postman](https://www.postman.com/) if you enable **Follow original HTTP method**.
Keep that option unchecked.
:::

![Avoid specifying HTTP method with redirects](/assets/postman-redirect-warning.png)

#### HTTP 400 Bad Request

You'll see an HTTP 400 response for one of two reasons:

- If your request was malformed (for example, you have a header `content-type: application/json`, but the data you sent wasn't valid JSON).

  ```txt title="Malformed payload"
  $ curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/example==' -v \
  --data "{bad-data" \
  --header "content-type: application/json"

  ...

  < HTTP/2 400
  < content-type: application/json
  < content-length: 44
  < date: Wed, 28 Sep 2022 19:47:09 GMT
  < x-amzn-requestid: 64a06065-c2d5-4d1b-8188-1513f072cb8e
  < access-control-allow-headers: Accept,CloudFront-Forwarded-Proto,CloudFront-Is-Desktop-Viewer,CloudFront-Is-Mobile-Viewer,CloudFront-Is-SmartTV-Viewer,CloudFront-Is-Tablet-Viewer,CloudFront-Viewer-ASN,CloudFront-Viewer-Country,content-type,Host,User-Agent,Via,X-Amz-Cf-Id,X-Amzn-Trace-Id,X-Forwarded-For,X-Forwarded-Port,X-Forwarded-Proto
  < x-amz-apigw-id: ZL6tYEjPCYcFmMA=
  < prismatic-executionid: SW5zdGFuY2VFeGVjdXRpb25SZXN1bHQ6YmIwZmQwMjgtYmRlOS00NDFhLTg4ZTYtNjcwZDlkMDY2NjZm
  < access-control-allow-methods: POST
  < x-amzn-trace-id: Root=1-6334a4bb-5a02f67725c134b505472c11;Sampled=1
  < x-cache: Error from cloudfront
  < via: 1.1 ee57d6770700357db4b696b4c5250b82.cloudfront.net (CloudFront)
  < x-amz-cf-pop: ORD58-P7
  < x-amz-cf-id: qSGjLnZJNDjUkUGU2Wl297s6eezPSFs5UEF58H_hceHj9JokJkfB3A==
  <
  * Connection #0 to host hooks.us-east-2.elasticpathintegrations.com left intact
  {"error":"Received malformed JSON payload."}
  ```

- When your webhook trigger is invoked [synchronously](#synchronous-and-asynchronous-integrations) and stops because an error is thrown, your request will receive an HTTP 400 response with the error that was thrown.

  ```txt title="Error thrown in synchronous execution"
  curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/example==' -v

  ...

  * We are completely uploaded and fine
  * Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
  < HTTP/2 400
  < content-type: application/json
  < content-length: 55
  < date: Wed, 28 Sep 2022 19:53:33 GMT
  < x-amzn-requestid: 8e46051e-2783-4e25-b95d-35ee323ce523
  < access-control-allow-headers: Accept,CloudFront-Forwarded-Proto,CloudFront-Is-Desktop-Viewer,CloudFront-Is-Mobile-Viewer,CloudFront-Is-SmartTV-Viewer,CloudFront-Is-Tablet-Viewer,CloudFront-Viewer-ASN,CloudFront-Viewer-Country,content-type,Host,User-Agent,Via,X-Amz-Cf-Id,X-Amzn-Trace-Id,X-Forwarded-For,X-Forwarded-Port,X-Forwarded-Proto
  < x-amz-apigw-id: ZL7paEZjiYcFU4A=
  < prismatic-executionid: SW5zdGFuY2VFeGVjdXRpb25SZXN1bHQ6NTM5ZGE0YjItNDViMC00MDQxLTg3MTgtMzFhZDkwMDg1Y2Iw
  < access-control-allow-methods: POST
  < x-amzn-trace-id: Root=1-6334a63c-0d58198b7c2e26d11f4331f3;Sampled=1
  < x-cache: Error from cloudfront
  < via: 1.1 26c731836eb716e46fe9852a7aaeb508.cloudfront.net (CloudFront)
  < x-amz-cf-pop: ORD58-P7
  < x-amz-cf-id: ZKCbTC07GI90gLLyeRNmGaHub0gpULRK45_GZ7d7uGM3njGFYKaPkw==
  <
  * Connection #0 to host hooks.us-east-2.elasticpathintegrations.com left intact
  {"error":"The widget requested is not in the database"}
  ```

#### HTTP 429 Too Many Requests / Rate Limiting

A webhook endpoint URL can be invoked up to 50 times per second.
If a request is received for an endpoint URL that has already received 50 requests in the last second, the request will receive a 429 "too many requests" response.

```txt title="Request rate limited"
$ curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/example==' -v

...

< HTTP/2 429
< content-type: application/json
< content-length: 200
< date: Wed, 28 Sep 2022 19:36:55 GMT
< x-amzn-requestid: f53fbf8c-9ce6-4c4a-80a6-84edbc29fdeb
< x-amz-apigw-id: ZL5NtH82CYcFbFg=
< x-amzn-trace-id: Root=1-6334a257-1ca7ad23574a8c3255b24776;Sampled=1
< x-cache: Error from cloudfront
< via: 1.1 a044221a7cde0fa9b5dc69d5ceb4439a.cloudfront.net (CloudFront)
< x-amz-cf-pop: ORD58-P7
< x-amz-cf-id: BoOs_sbk7gB-t16ZCR4uVtD8NcPnmD40rGUPwgaouVe2hiHu60Rcjw==
<
* Connection #0 to host hooks.us-east-2.elasticpathintegrations.com left intact
{"error":"Endpoint with id: example== has exceeded maximum allowed throughput of 50 requests/second. Please throttle your requests."}
```

### Webhook endpoint configuration

Webhook triggers can be configured for in integration in one of three ways:

- **Instance and Flow Specific**: Each flow on each instance gets its own unique endpoint. This is the default configuration.
- **Instance Specific**: Each instance gets a unique endpoint, and the integration determines which flow to run based on header or payload data.
- **Shared**: All customers' instances of the integration share an endpoint. Data in the header or payload determines which customer and flow should run.

For information on configuring and troubleshooting webhook endpoints, see our [Endpoint Configuration](/docs/composer/builder/integrations/integrations-triggers/endpoint-configuration) article.

### Sending data to webhook triggers

A webhook parses data from the following sources:

- The **request body** - the JSON (or other) data that is sent to the webhook as an [HTTP request body](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#body).
- The **request headers** - the [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages#headers).
- The **URL path** - The [path to resource](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#path_to_resource) that follows the integration webhook URL.
- The **URL parameters** - The [parameters](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#parameters) that follow the `?` in a URL..

Take, for example, this `curl` invocation:

```bash
curl \
  'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==/my/custom/path?param-one=ParamValueOne&param-two=ParamValueTwo' \
  --header "header-one: First header value" \
  --header "header-two: Second header value" \
  --header "Content-Type: application/json" \
  --data '{"Payload Key 1":"Payload Value 1","Do Thing?":true,"quantity":123}'
```

- The request body - `{"Payload Key 1":"Payload Value 1","Do Thing?":true,"quantity":123}` - is parsed (if JSON) and is accessible to the integration by referencing the trigger's `results.body.data.KEY-NAME`. Non-JSON payloads (like XML, images, etc) are accessible through `results.rawBody` and can be parsed in subsequent steps that handle that type of data.
- The request headers are accessible through the trigger's `results.headers.HEADER-NAME`.
- The url path - `my/custom/path` - is accessible through the trigger's `results.pathFragment`. You can pass that data into the built-in split string action and split on the `/` character to split the URL path into an array `['my','custom','path']`.
- The url parameters - `?param-one=ParamValueOne&param-two=ParamValueTwo` are parsed and accessible through the trigger's `results.queryParameters.PARAMETER-NAME`.

![Screenshot of Sending Data to Webhook Triggers](/assets/sending-data-to-webhook-triggers.png)

### Posting binary data with webhook triggers

If you have binary data (like an image or PDF) that you would like to post as part of your webhook invocation, you can pass that binary data in as part of your request.
For example, if you have an image, `my-image.png`, you could invoke a test of an integration with:

```bash
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
  --request POST \
  --header 'Content-Type: image/png' \
  --data-binary '@/path/to/my-image.png'
```

The binary file can be accessed by subsequent steps by referencing `integrationTrigger.results.body.data`.

### Posting multipart data with webhook triggers

It's useful to be able to post a combination of binary and text data to a Prismatic webhook.
For example, you might want to post information about a person, as well as an avatar image of the person, to be processed by an integration.
To do that, use a content type of `multipart/form-data` with your webhook invocation:

```bash
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
  --request POST \
  --header "Content-Type: multipart/form-data" \
  --form person='{"firstname":"Taylor","lastname":"Reece"};type=application/json' \
  --form photo=@taylor.png
```

The first name in this example is accessible by referencing the trigger's `results.body.data.person.data.firstname`, and the avatar image is accessible by referencing `results.body.data.photo`:

![Post multipart data with webhook triggers](/assets/webhook-multipart-payload.png)

### Accessing webhook URLs in an integration

An integration is aware of its own webhook URLs, and those URLs are accessible by referencing the trigger's `results.webhookUrls` object:

![Access webhook URLS for integration](/assets/webhook-urls-payload.png)

This comes in handy if you need to configure a third-party service to send data to your webhooks.
A common pattern is for one [flow](/docs/composer/builder/integrations/building-integrations#flows-in-integrations) of your integration to be run when an instance is deployed using a [deploy trigger](#deploy-trigger).
That deploy-time flow can set up webhooks in a third-party app by referencing its trigger's `results.webhookUrls` values.
Then, the third-party app will invoke the other flows of the integration when it needs to.

If you set up API keys for your deployed instances, you can access `results.webhookApiKeys` similarly.
An instance's flow can have multiple API keys assigned to it, so each `results.webhookApiKeys.MY FLOW NAME` is an array.
You will likely reference the first API key, `results.webhookApiKeys.MY FLOW NAME.0`.

## Validating webhook payloads with HMAC

**Hash-Based Message Authentication Code** (or HMAC) is an authentication mechanism often used by webhook providers to verify that a webhook message is legitimate.
It helps to ensure that messages sent to a webhook endpoint originated from a particular third-party, and not from some bad actor on the internet.

### How does HMAC work?

HMAC implementations can differ slightly from one another, but generally speaking when a webhook request is sent to an endpoint, the request's body is hashed using a **secret key** and [hash function](https://en.wikipedia.org/wiki/Cryptographic_hash_function).
The resulting **hash** is sent with the webhook HTTP request as an HTTP header.

When the webhook endpoint receives the HTTP request, it also generates a hash using same secret key and hash function.
If the hash the receiver generates matches the hash that the sender sent, the webhook request is processed.
If they don't match, the request is rejected.

In order to spoof a webhook request, someone would need to know the secret key that only the sender and receiver know.
Without the secret key (even if a bad actor intercepted the webhook request), it'd be [nearly impossible](https://stackoverflow.com/questions/44472974/how-long-time-would-it-take-to-decrypt-a-sha256-hash) for a bad actor to reverse engineer the hash and send spoofed requests to a webhook endpoint.

### Generating an HMAC hash

You can configure your app to compute HMAC hashes and send them alongside your webhook requests.
To generate a hash, you need three things:

1. A request's **body** to hash.
   The body can be any format (JSON, XML, CSV, etc).
   For our example, let's say we have a JSON message that reads `{"item":"widget","quantity":5,"customer":"abc-123"}`.
1. A **secret key** that only the third-party and Prismatic knows.
   For our example, we'll generate a random UUID string - `"AC49CB66-511F-4085-9119-360B1B142F4B"`
1. A **hash function** to use (like MD5, SHA1, etc.).
   The industry standard (which APIs like Dropbox, Shopify, Slack, etc. all use) is `SHA256` - we'll use that for our example, too.

Next, reach for an HMAC library for the language that your app is written in (most modern languages have an HMAC or crypto library).
Here's a few examples in a variety of languages:

#### Python

```python title="HMAC example written in Python3"
import hmac
import hashlib

secret = bytes("AC49CB66-511F-4085-9119-360B1B142F4B", "UTF-8")
message = '{"item":"widget","quantity":5,"customer":"abc-123"}'.encode();

hash = hmac.new(secret, message, hashlib.sha256)

print(hash.digest().hex()) # dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf
```

#### NodeJS

```javascript title="HMAC example written in NodeJS"
const { createHmac } = require("crypto");

const secret = "AC49CB66-511F-4085-9119-360B1B142F4B";
const message = '{"item":"widget","quantity":5,"customer":"abc-123"}';

const hash = createHmac("sha256", secret).update(message, "utf-8");

console.log(hash.digest("hex")); // dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf
```

#### PHP

```php title="HMAC example written in PHP"
<?php
  $message   = '{"item":"widget","quantity":5,"customer":"abc-123"}';
  $secret    = 'AC49CB66-511F-4085-9119-360B1B142F4B';

  $hash = hash_hmac('sha256', $message, $secret);

  echo ($hash); // dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf
?>
```

#### GO

```go title="HMAC example written in Go"
package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "fmt"
)

func main() {
  secret := []byte("AC49CB66-511F-4085-9119-360B1B142F4B")
  message := []byte("{\"item\":\"widget\",\"quantity\":5,\"customer\":\"abc-123\"}")

  h := hmac.New(sha256.New, secret)
  h.Write(message)
  hash := hex.EncodeToString(h.Sum(nil))

  fmt.Println(hash) // dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf
}
```

Regardless of which language you use to generate the HMAC hash, you get the same result for our example - `dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf`.
You can then pass the hash as an HTTP header to our Builder webhook URL.

```bash
curl https://hooks.us-east-2.elasticpathintegrations.com/example-uuid \
  --request POST \
  --header "my-hmac-header: dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf" \
  --header "content-type: application/json" \
  --data '{"item":"widget","quantity":5,"customer":"abc-123"}'
```

**Can I include the HMAC hash in the body instead?**
That's a common question, and the answer is a resounding **no**.
By adding the HMAC hash to the body, you change the body... so a different body hash is computed... which requires you to change the body... (GOTO 10).
An HMAC hash should be sent via a header.

### Validating HMAC hashes in a trigger

If your HMAC hash is generated from the HTTP payload's body, the secret signing key is a string, and the hash is included as a header, you can use the built-in HMAC Webhook Trigger to validate payloads.
Configure the trigger by setting the name of the header that contains the HMAC hash (e.g. `x-hmac-sha256`), the hashing function you used (e.g. `sha256`), and the secret key you used, and the trigger will accept payloads that are properly signed, and throw an error when payloads are not signed correctly.
The trigger otherwise operates like the standard built-in webhook trigger.

If the app you're integrating with deviates from standard HMAC signing practices, or if you need to respond to webhook requests with dynamic responses, you can build your own custom trigger that handles HMAC validation.
Slack, for example, includes an additional parameter (a timestamp) in its HMAC computation, and expects a custom response from the webhook endpoint.

## Instance deploy trigger

An integration flow can be configured to be run when an instance of the integration is deployed.
To do that, click your trigger and then click **CHANGE TRIGGER**.
Choose to replace your trigger with an [Instance Deploy Trigger](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#instance-deploy-trigger) trigger.
This will cause your current flow to run whenever the integration is deployed as an instance to a customer.

This is handy if your integration needs to complete a series of tasks when its deployed.
For example, your integration might need to configure a third-party app to send data to the other flows' webhooks.
Or, your integration might need to enable features in a third-party app or create a series of directories in a file share before the integration is invoked.

If there are tasks that need to occur when an instance is deployed, set up those tasks as a flow and configure the trigger to run at deploy time.

**For More Information**:
[Multiple Flows with a Deploy Trigger](/docs/composer/builder/quickstarts/integrations/building-an-integration-with-multiple-flows)

## Instance remove trigger

The opposite of an [instance deploy trigger](#instance-deploy-trigger) is an [instance remove](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#instance-remove-trigger) trigger.
Flows with this trigger run when an instance is removed (deleted), and can be used to clean up webhooks and other configuration that an instance deploy trigger created.

## Synchronous and asynchronous integrations

Integrations are configured by default to run **asynchronously**.
That means that whenever an integration is invoked by trigger webhook URL, the integration begins to run and the system that invoked the integration can go on to complete other work.
This is the most common case for integrations - you want to start up an instance when some certain event occurs, but you don't want to wait around while the instance runs.

Sometimes, though, it's handy for an application to get information back from the instance that was invoked.
For example, you might want your proprietary software to wait until an instance runs to completion before completing other work.
In that case, you can choose to run your integration **synchronously**.
Then, when your software makes a call to the instance's webhook trigger URL the HTTP request is held open until the instance run is complete.

When you choose to run your integrations **synchronously**, the HTTP request that invokes an instance returns a _redirect_ to a URL containing the output results of the final step of the integration.
For example, if the final step of your integration pulls down JSON from https://jsonplaceholder.typicode.com/users/1, you will see this when you invoke the integration synchronously:

```bash
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
  --data '{}' \
  --header "Content-Type: application/json" \
  --header "prismatic-synchronous: true" \
  --location

{"id":1,"name":"Leanne Graham","username":"Bret","email":"Sincere@april.biz","address":{"street":"Kulas Light","suite":"Apt. 556","city":"Gwenborough","zipcode":"92998-3874","geo":{"lat":"-37.3159","lng":"81.1496"}},"phone":"1-770-736-8031 x56442","website":"hildegard.org","company":{"name":"Romaguera-Crona","catchPhrase":"Multi-layered client-server neural-net","bs":"harness real-time e-markets"}}
```

You can toggle if your integration is synchronous or asynchronous by clicking the trigger and selecting a **Response Type**.

You can also pass in a header, `prismatic-synchronous` with a webhook invocation to instruct your instance to run synchronously or asynchronously:

```bash
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
  --header "prismatic-synchronous: false" \
  --request POST
```

#### Synchronous invocations and redirects

When you invoke an instance synchronously, the output of the final step of your integration is written to Amazon S3.
The HTTP request that invoked the integration execution then receives a response that redirects them to the file in Amazon S3.
We do this because Amazon's API Gateway has a 10MB limit on HTTP responses, and step results may exceed 10MB - S3 has no such size limit.

Because of this redirection, you should make sure that your request library is configured to follow HTTP status code 303 redirects.
For `curl`, for example, include a `-L / --location` flag so it follows redirects.

If the party initiating the instance execution request does not support following redirects, they can pass an optional header, `prismatic-prefer-direct-sync-response: true` with their request to skip the redirect to S3, and return the response directly.
Note that this only works for step results less than 5MB in size, and your last step's results must be text-like (i.e. JSON, XML, plain text, etc - not a binary file).
If your final step's output is greater than 5MB, they'll be redirected to S3.
This works well if your final step's result is text.

```bash title="Skip the redirect to Amazon S3"
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
  --request POST \
  --data "{}"
```

If the third-party also doesn't support custom headers, you can append `prismatic-prefer-direct-sync-response=true` as a search parameter:

```bash title="Skip the redirect to Amazon S3 with a search parameter"
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==?prismatic-prefer-direct-sync-response=true'
```

:::tip 
Response content type
You can control the `content-type` of the response by adding a `contentType` property to your last step's result.
For example,

```typescript
const returnData = `<note>
    <to>Tove</to>
    <from>Jani</from>
    <heading>Reminder</heading>
    <body>Don't forget me this weekend!</body>
</note>`;

return {
  data: returnData,
  contentType: "application/xml",
};
```
:::

### HTTP status codes for synchronous integrations

When an instance is configured to run synchronously or is invoked synchronously with the `prismatic-synchronous` header, the HTTP response returns a status code `200 - OK` by default.
It's sometimes useful, though, to return other HTTP status codes.
For example, if a client submits wrongly formatted data to be processed by an instance, it might be helpful to return a `406 - Not Acceptable` or `415 - Unsupported Media Type`.

To accomplish this, you can configure the final step of your integration to return a different status code.
Most commonly, you can add a Stop Execution step to the end of your integration, and specify an HTTP response that it should return.

![Configure HTTP status codes for synchronous integrations](/assets/stop-execution-status-code.png)

```bash
$ curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
   --verbose \
   --location \
   --header "prismatic-synchronous: true"

* TCP_NODELAY set
* Connected to hooks.us-east-2.elasticpathintegrations.com (13.227.37.2) port 443 (#0)

...

< HTTP/2 415
```

If you would like to return HTTP status codes from a custom component at the end of your integration instead, return an object with a `statusCode` attribute instead of a `data` attribute:

```javascript
return { statusCode: 415 };
```

### Synchronous call limitations

#### Response body and status code limitations

When an integration is invoked synchronously, the integration redirects the caller to a URL containing the output results of the final step of the integration.
If the final step of the integration is a Stop Execution action, or any custom component action that returns a `statusCode`, the redirect does not occur and the caller receives a `null` response body instead.

#### API gateway size and time limitations

AWS API Gateway times out requests after 29 seconds, and our maximum response size is 500MB.
So, to get a response from an instance that is invoked synchronously, please ensure that your integration runs in under 29 seconds and produces a final step payload of less that 500MB.

If your integration regularly takes over 29 seconds to run, or produces large responses, we recommend that you run your integrations asynchronously instead.
When you invoke an integration asynchronously you receive an `executionId`:

```bash
curl 'https://hooks.us-east-2.elasticpathintegrations.com/trigger/EXAMPLE==' \
  --data '{}' \
  --header "Content-Type: application/json"

{"executionId":"SW5zdGFuY2VFeGVjdXRpb25SZXN1bHQ6OTdiNWQxYmEtZGUyZi00ZDY4LWIyMTgtMDFlZGMwMTQxNTM5"}
```

---

## Overview(Integrations)

An **integration** is a series of **steps** that execute one after another in series.
Each step runs an action - a small bit of code designed to perform a specific task.
Actions can be things like **HTTP - GET** to fetch the contents of a webpage from the internet, or **Amazon S3 - Put Object** to save a file to Amazon S3.
You can use a combination of actions from common built-in components to build an integration.

An integration is started when its **trigger** fires.
Triggers can either follow a [schedule](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#scheduled-triggers), or can be invoked via a [webhook URL](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#webhook-triggers).

Integrations should be developed to be **configuration-driven**, so they can be deployed to multiple customers with potentially different configurations.
That is accomplished by leveraging [config variables](/docs/composer/builder/integrations/building-integrations#config-variable-inputs), and have configuring steps to reference those variables.

Many integrations have a single **flow**.
That is, they have a single trigger that fires, and a single set of steps that are executed one after another.
Builder also supports grouping multiple related flows together into a single deployable integration.
For example, if you have a third-party service (Acme ERP) that sends data via a variety of webhooks to your integrations, it probably makes sense to have a single Acme Corp integration that you or your customers deploy that is made up of several logical flows.
Each flow has its own trigger, though they all share config variables.

When an integration is completed, it can be [published](#publishing-an-integration).
You can then enable the integration through the [Integration Hub](/docs/composer/integration-hub/integrations-hub).

We recommend that you follow our [Getting Started](/docs/composer/builder/getting-started/build-first-integration) tutorials to first acquaint yourself with integration development and deployment.

## Creating a new integration

To create a new integration in the web app, click **Integrations** from the left-side menu, and then click the **+ Add Integration** button in the upper-right.

When you create a new integration you have a few options:

- You can create a **blank** integration from scratch.
- You can start from an existing [template](/docs/composer/builder/integrations/overview#integration-templates) that you or someone else created.
- Behind the scenes, integrations are saved as [YAML definitions](#yaml-definition).
  You can load a YAML file from your clipboard or from a file.

![Configure a new integration](/assets/configure-new-integration.png)

You will be prompted to give your integration a **name** and **description**, and can optionally [categorize](#categorizing-integrations) your integration and assign it [labels](#integration-labels).

![Add integration](/assets/new-integration-name.png)

Next, you'll be asked to select a trigger for your integration.
This is what will cause your integration to run, and you can change your trigger at any time.

![Select integration trigger](/assets/new-integration-trigger.png)

For more information, see:
- [Building Integrations](/docs/composer/builder/integrations/building-integrations)
- [Testing Integrations](/docs/composer/builder/integrations/testing-integrations)

## Integration templates

Some of your integrations will look similar to one another.
For example, if you are importing opportunities and accounts from a dozen CRM vendors, the steps that fetch data will be unique, but the steps that send data to your app will always look the same.
Rather than developing those common steps over and over, it saves time to create an integration template that you and your team can start from when you build additional similar integrations.

To turn your integration into a template, first [publish](#publishing-an-integration) a version of your integration.
Then, open the **Details** dropdown and select **Available as Template**.

![Create a new template of an integration](/assets/available-as-template.png)

You can choose if the template is just for org users.

## Assigning an icon to an integration

Integrations can be assigned icons, to make them more presentable in the [Integration Hub](/docs/composer/integration-hub/integrations-hub).
To assign an icon to an integration from the integration designer by clicking the icon to the left of your integration's name:

![Add icon to integration](/assets/add-icon.png)

Square PNG images that are at least 400 pixels wide look best as integration icons.

![Assign labels to integration](/assets/labels.png)

## Integration labels

Labels help you keep your integrations organized.
You can assign any number of labels to an integration from within the integration designer by opening the **DETAILS** menu:

You can [search](#listing-and-searching-integrations) for integrations by label.
*Note*: for consistency, labels are always lower-cased.

If you would like to update labels on previously published versions of your integration, open the **VERSION HISTORY** drawer and select a previously published version of your integration.
Add labels from the **DETAILS** menu, and click **Save**.

![Update labels for prior published versions of integration](/assets/label-versions.png)

Labels applied to published integration versions appear in the version dropdown menu on an instance configuration page.

![Versions and labels for instance configuration](/assets/label-versions-instance.png)

## Listing and searching integrations

To view all of the integrations your organization has created, click the **Integrations** link on the left-hand sidebar.

![All integrations for organization](/assets/list-integrations.png)

You can search for specific integrations by name by typing a part of the name in the upper search bar, or you can search by **description**, **[category](#categorizing-integrations)**, **[labels](#integration-labels)** or **marketplace availability** by clicking the **Filter** button to the right of the search bar.

![Filter integrations](/assets/search-integrations.png)

## Categorizing integrations

Integrations can be assigned a "category" for easy sorting and filtering.
For example, you might have a dozen "ERP" integrations, a few "Inventory Management" integrations, etc.
Assigning each integration a category allows your team, as well as your customers in the [Integration Hub](/docs/composer/integration-hub/integrations-hub) to view integrations sorted by category.

You can set a category for an integration by clicking the **DETAILS** dropdown button on the top-left of the integration designer:

![Set category for integration](/assets/edit-name-description.png)

## Publishing an integration

By **publishing** an integration, you mark it ready for deployment.

To publish an integration, first open the **VERSION HISTORY** tab on the left side of the page.
If you have unpublished changes you'll see an **Unpublished Draft** listed among the integration's versions.
Type a note about the changes you made to the integration, and then click **SAVE & PUBLISH** to release a new version of your integration:

![Publish integration](/assets/version-history.png)

Integration versions can be marked **Available** or **Unavailable** by toggling the blue toggles to the right of integration versions. Marking an integration version **Unavailable** prevents that version from being deployed.

## Deploying an integration

Once an integration has been [published](#publishing-an-integration), an instance of the integration can be configured and deployed to a customer.

You can also enable your customers to deploy integrations themselves, using [Integration Hub](/docs/composer/integration-hub/integrations-hub).

## Viewing deployed integrations

To view a deployed integration, in Builder, click the **Marketplace Configuration** tab.

![List of deployed instances](/assets/list-instances.png)

## Forking an integration

Sometimes you will want to make a copy of an integration and modify the copy.
This is called *forking* an integration.

From the integration designer, click the **Settings**. icon on the bottom left of the page.
Then, click **Fork Integrations**.
Give your forked integration a new name and description and then click **ADD**.

## Deleting an integration

:::caution
Use caution when deleting an integration. Deletion of an integration also deletes all deployed instances of that integration.
:::

From the integration designer, click the **Settings** icon on the bottom left of the page.
Click the **Delete Integration** button on the bottom of the page and confirm by clicking **REMOVE INTEGRATION**.

## Integration attachments

Your team can save and share integration-related documents alongside an integration by clicking on the **Attachments** tab from the integration designer page.

![Add attachments to integration](/assets/attachments.png)

## Internal integration documentation

It's helpful to share documentation, specs and notes about an integration with your team members.
You can add internal (non-customer-facing) notes and documentation to an integration by clicking the **Integration Documentation** button on the right-hand side of the integration designer.
This will open up a drawer on the right-hand side of the designer.

The drawer has two tabs: **Edit** and **Preview**.

In the **Edit** tab you can type [Markdown syntax](https://www.markdownguide.org/basic-syntax/), including external links, code snippets and externally-hosted images:

![Add internal integration documentation](/assets/documentation-markdown.png)

In the **Preview** tab you can view the rendered markdown:

![Preview internal integration documentation](/assets/documentation-rendered.png)

## YAML definition

Behind the scenes, integrations are represented in YAML.
You can view the YAML that defines your integration's flows, steps, inputs, connections and config variables by clicking **Manage** at the bottom-left of Builder, and selecting **Save/Load**.

![YAML for integration](/assets/yaml-definition.png)

If you are exporting the integration and importing it in a different region (US -> EU, for example), make sure you click a **latest component versions** button, as component versions may not match between regions.

:::note
The YAML present in this drawer corresponds to the integration that is currently being displayed.
You can view the YAML of a previous version of the integration by first opening the **VERSION HISTORY** drawer and selecting an older integration version.

If you want to spot differences between an older version of your integration and the current version, you can compare the YAML definition of the older version with the YAML definition of the current version using your favorite diff tool (VSCode has a great built-in [diff tool](https://vscode.one/diff-vscode/)).

:::

### Exporting an integration

Once you've opened the **Save/Load** drawer in the integration designer, you can click **Copy to clipboard** to copy the integration's YAML definition into your clipboard, so you can paste it into an editor of your choice.
You can also click **Save to file** to download a copy of your integration.

### Importing an integration

If you have a YAML definition of your integration saved in your clipboard, you can click **Load from clipboard** to replace your current integration with the definition that you have copied.
Or, you can save a modified YAML file to your computer, and load the YAML definition by clicking **Load from file** and selecting the file you saved.

---

## Testing Integrations

Builder provides a sandbox for testing integrations. From Builder you can invoke an integration, configure test values for config variables, and view test logs in real time.

You can test your integration after you set test values for config variables by clicking the **SAVE & RUN TEST** button.

If your integration is made up of multiple [flows](/docs/composer/builder/integrations/building-integrations#flows-in-integrations), each flow is tested independently.
Click the flow name on the top left of the Builder area, select the flow you would like to test, and then click **SAVE & RUN TEST**.
Note that each flow has a distinct webhook URL, so if you are invoking the integration from a third-party app via webhook, you'll need to note the flow's webhook URL.

## Test config variables

If your integration uses config variables, you can specify testing values for those variables under the **Configuration** tab of the **Test Runner** drawer.
If you specified default values for your [config variables](/docs/composer/builder/integrations/building-integrations#config-variables-in-integrations), those will be preset for you.
Otherwise, fill in testing values and credentials for the purposes of testing your integration.

![Configure test for integration](/assets/test-config-variables.png)

We recommend that you create testing, non-production sandbox credentials for integration tests.

## Test run outputs

After running an integration test, the output of each step is available in the **Step Outputs** tab of the **Test Runner** drawer.
Select which step you would like to see results for from the dropdown menu.
You can reference those results in subsequent steps.
This is helpful for debugging and verifying the flow of data within your integration.

![Step outputs for tests](/assets/test-outputs.png)

## Test run logs

Output for your test run is displayed under the **Logs** tab in the **Test Runner** drawer.
If any of your steps log output or throw errors, you will see those logs and errors in this window.

![Logs for tests](/assets/test-logs.png)

## Testing a webhook trigger

An integration can be invoked via webhook.
This is useful if you have a third-party system that sends data to an integration to be processed.

To test a webhook invocation of an integration, open the **Trigger** tab of the **Test Runner** drawer and take note of the "POST URL".

You can use that URL to invoke a test of your integration, just as you would to invoke an execution of a deployed instance - see our [webhook trigger](/docs/composer/builder/integrations/integrations-triggers/how-to-use-integration-triggers#webhook-triggers) docs.
You can also specify a **test payload body** to be processed by the integration, and if your integration requires custom HTTP **headers**, those can be specified under the test payload body.

### Replaying test invocations

:::note
You can replay a test integration invocation. That comes in handy if you are testing an integration invocation from a third-party app. You don't need to set up your third-party environment every time - you can fire off a webhook invocation once from your third-party app with a payload, and run that same payload through your integration until you're happy with the results.
:::

To replay a test integration invocation, open the **Test Runner** drawer and click into the **Runner** tab.
Click the **Replay** icon to the right of the test that you would like to replay.

![Replay test integration invocation](/assets/test-integration-replay.png)

The payload that was sent to trigger this integration test will be fed back into another test of the integration.
This allows you to make changes to your integration and iterate quickly, without needing to reconfigure your third-party apps and services to fire new webhook requests over and over.

---

## Troubleshooting Integrations

## Common Error Messages

This page outlines common error messages that you may see, and how to fix them.

### P10001: Result too large to serialize

You may see this error when dealing with large files (greater than 128MB) due to limitations on how large a JavaScript `Buffer` can be.
Reduce the size of your step result if possible.

### P10002: Result contains non-serializable functions

You may see this error if your step result contains JavaScript functions.
Builder serializes step results using [MessagePack](https://msgpack.org/index.html).
JavaScript functions are non-serializable.
So, you cannot `return { data: { foo: () => "" } }`, for example.

As a work-around, you can JSON stringify and JSON parse an object, and functions will be automatically removed.

```typescript
const myReturnValue = {
  foo: 123,
  bar: "Hello, World",
  baz: () => {
    console.log("Hi!");
  },
};
const sanitizedResults = JSON.parse(JSON.stringify(myReturnValue));
return { data: sanitizedResults }; // Returns {foo: 123, bar: "Hello, World"}
```

### P10003: Error serializing step results

An unknown error occurred when serializing your step results.
Builder serializes step results using [MessagePack](https://msgpack.org/index.html).
MessagePack supports a number of complex and primitive types (numbers, strings, objects, arrays, Buffers, null, etc).
Ensure that the data you are returning is included in the [MessagePack spec](https://github.com/msgpack/msgpack/blob/master/spec.md).

---

## Overview(Builder)

Builder is a Commerce integration platform for Commerce customers. It's the quickest way to build integrations to the other apps that you use. You can do this using the Commerce pre-built components. 

Builder significantly reduces overall integration effort and enables non-dev teams to take on more of the integration workload, so that you can deliver integrations faster and spend more time on customer experience.

With Builder, you can:

- Build reusable integrations in a low-code integration designer.
- Use pre-built components to handle most of your integrations' functionality.
- Easily deploy customer-specific integration instances with unique configurations and connections.
- Provide better support with tools like logging and alerting.
- Run your integrations in a purpose-built environment designed for security and scalability.

## Types of Integrations 

You can build the following types of integrations with Builder.

- Search providers, like Algolia or Coveo, enable your customers to search your Commerce products using a third-party search provider.
- Order management providers, like Onport or Fluent, enabling support for marketplace and drop-ship vendor models in Commerce. 
- Product management providers, like Pimberly or Salsify, to synchronize catalog data such as products, price, images, and categories between Commerce and a third-party product management provider.
- Marketing & Communication providers like SendGrid or Braze, allows you to share customer profile information, or send emails to your customers when events in Commerce are triggered. For example, you can send a customer registration email when you create a customer in Commerce.
- Manage your Commerce stores by integrating with the Commerce component. For example, exporting and importing products between stores.

## Integrations

You can assemble an integration by tying together multiple components' actions. That integration can be tested. Once you are satisfied with your integration, it can be published, and instances of the integration can be configured and deployed to Integrations Hub where it can be activated.

Instances are deployed using your specific config variables.

## Logging, Monitoring, and Alerting

When an integration behaves unexpectedly (takes too long to run, or fails to run to completion), you want your team to be notified. Alert monitors can be configured to monitor your instances, and notify your team in the event of an issue. Logs of all instance runs are retained, so you can debug production issues and rapidly resolve problems.

Not all alerts indicate bad things happened; alert monitors can be configured to run when an instance is enabled (so you can mark implementations as complete), or can be configured to alert you via Slack or Email that an integration that runs daily ran successfully.

---

## Using a Code Component to Transform Data

Builder's code component lets you incorporate custom JavaScript code anywhere in your integration.
The code component allows you to write the product- or industry-specific portions of your integration that aren't readily solved using built-in components from the [component catalog](/docs/composer/builder/builder-components/epcc).

As a reminder here: code components are handy to write simple one-off, single integration code snippets.

## Today's problem

Today we'll address a problem that B2B companies often see when working with third-party vendors: data not coming in within an agreed upon spec.
Suppose that we and a third-party vendor agreed that we would be sent JSON-formatted data via webhook payload that looked like this:

```json
[
  {
    "firstName": "John",
    "lastName": "Smith",
    "dob": "1987-05-20",
    "userid": "123"
  },
  {
    "firstName": "Jane",
    "lastName": "Smith",
    "dob": "1992-07-16",
    "userid": "172"
  }
]
```

Our integration worked during testing with sample data, but when we turn on our integration for third-party vendor consumption, errors are generated when our integration tries to parse the data that was sent.
Logs indicate that the data the vendor is sending is formatted entirely differently than what we agreed to:

```json
{
  "123": {
    "name": "John Smith",
    "dob": "05/20/1987"
  },
  "172": {
    "name": "Jane Smith",
    "dob": "07/16/1992"
  }
}
```

The other vendor drags its feet, and claims a fix is a "long ways off".
We don't have time to wait for the other vendor to fix its software - we need the integration working!
We can fortunately implement a quick fix by adding a code component to the top of our integration to transform the malformed data into the format we expect.

## Using a code component as a shim

Our integration was written to expect one format of input, but received another.
We need to transform the data like this:

```json
{
  "123": {
    "name": "John Smith",
    "dob": "05/20/1987"
  }
}
```

into something like this:

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "dob": "1987-05-20",
  "userid": "123"
}
```

That should be pretty easy to do.
We really just need to do three things:

- Split the name at the space character to form a first and last name
- Reformat the date of birth into a more reasonable format
- Pull the JSON key ("123") into a value of `userid`

If we add a code component to our integration, by default it reads:

```javascript
module.exports = async (context, stepResults) => {
  const results = null; // Result of calculation, API request, etc.
  return { data: results };
};
```

The first thing I want to do is use JavaScript destructuring to capture the JSON that the third-party vendor sent as part of the integration trigger's webhook payload:

```javascript
module.exports = async (
  { logger },
  {
    integrationTrigger: {
      results: {
        body: { data: userData },
      },
    },
  }
) => {
  logger.info(userData); // Verify we're capturing in user data properly
  const result = null;
  return { data: result };
};
```

Looking at logs, it looks like we've written our destructuring correctly.
Let's next [map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) over the objects (users) that we were sent with `Object.entries(userData).map()`.

Each iteration of our `map()` will generate an object with `firstName`, `lastName`, `dob`, and `userid`.
We'll reformat the date of birth with the `Date()` object, split the name that was provided to us into a first and last name using `split()`, and grab the `userid` from the keys that were provided to us:

```javascript
module.exports = async (
  { logger },
  {
    integrationTrigger: {
      results: {
        body: { data: userData },
      },
    },
  }
) => {
  const result = Object.entries(userData).map(([userid, user]) => {
    const dob = new Date(Date.parse(user.dob)).toISOString().slice(0, 10);
    const firstName = user.name.split(" ").slice(0, -1).join(" ");
    const lastName = user.name.split(" ").slice(-1).join(" ");
    return {
      firstName,
      lastName,
      dob,
      userid,
    };
  });
  return { data: result };
};
```

That's it!
The rest of our integration can now be configured to reference the results of the code component rather than the body of the integration payload, and it'll start working as we'd expect it to despite the poorly formatted JSON from the third-party vendor.
We can see from a test of our code component that our code component is reformatting data like we expect it to:

![Step outputs in integration designer](/assets/results.png)

---

## Generating a PDF with a Code Component

In this quickstart we'll write a short code component snippet that references some JSON data, and outputs a rendered PDF file.
We'll cover how to import external libraries in a code component, and how to output binary data (like a PDF file) from a code component.

For this example, assume that our integration receives a list of rocket launches that have occurred recently in JSON format:

```json
[
  {
    "rocketName": "Deep Space 9",
    "launchTime": "2020-10-27T20:29:46.139Z",
    "launchSupervisor": "Robert Smith",
    "launchNotes": "Rocket was launched into orbit where it will remain for several months."
  },
  {
    "rocketName": "Voyager",
    "launchTime": "2020-10-27T21:34:15.229Z",
    "launchSupervisor": "Sally Smith",
    "launchNotes": "Rocket launched without a hitch. Thrusters were retrieved 30 minutes after launch."
  }
]
```

We would like to generate PDF files from this data with launch information, one launch per page, for managers to print and read through.

## Importing external libraries

Today we'll use the [PDF-LIB](https://www.npmjs.com/package/pdf-lib) library to render our PDF.
To do that, let's add the following to the top of a new code component in our integration:

```javascript
const {
  PDFDocument,
  StandardFonts,
} = require("pdf-lib@1.11.2/dist/pdf-lib.js");
```

It's wise to pin requirements to known working versions.
Since we're testing our integration with PDF-LIB version 1.11.2, we'll select that specific version.
If we omitted the version, our integration would import whatever latest version is available.

Adding this `require()` line to the top of our code component will cause the code component to [dynamically import](/docs/composer/builder/components/code-component-usage#adding-dependencies-to-a-code-component) the PDF-LIB library as a dependency.

## Writing our code component snippet

Next, we'll write the code that generates a PDF.
Let's first test that we can generate a blank PDF file:

```javascript
const { PDFDocument } = require("pdf-lib@1.17.1/dist/pdf-lib.js");

module.exports = async (context, stepResults) => {
  const doc = await PDFDocument.create();
  const pdfBytes = await doc.save();
  return { data: pdfBytes, contentType: "application/pdf" };
};
```

If we run this code component and look at step outputs, we see that our code component generated a 583 byte binary file.
By adding a **Save File** step after the code component to GCP Storage, and we can write that blank file out to GCP storage to verify that it looks like we'd expect.
You can choose to write the file out to Amazon S3, Azure, an SFTP share, DropBox, etc... your choice.

We now have a blank PDF written out.
What's left to do is add some text to the PDF based on the data that was presented to our integration's webhook:

```javascript
const {
  PDFDocument,
  StandardFonts,
} = require("pdf-lib@1.17.1/dist/pdf-lib.js");

module.exports = async (context, stepResults) => {
  // Pull in data from the webhook trigger payload
  const rocketLaunches = stepResults.integrationTrigger.results.body.data;

  // Generate a PDF Document
  const doc = await PDFDocument.create();

  // Embed the Times Roman font
  const timesRomanFont = await doc.embedFont(StandardFonts.TimesRoman);

  // Loop over each rocket launch, adding a page to our document for each one
  rocketLaunches.forEach((rocketLaunch) => {
    const {
      rocketName,
      launchTime,
      launchSupervisor,
      launchNotes,
    } = rocketLaunch;

    // Create a new page for each launch
    const page = doc.addPage();
    const { width, height } = page.getSize();
    const _launchTime = new Date(launchTime).toLocaleString();

    // Print information about the launch
    page.drawText(`Rocket: ${rocketName}`, {
      x: 30,
      y: height - 120,
      size: 30,
      font: timesRomanFont,
    });

    page.drawText(`Launch Time: ${_launchTime}`, {
      x: 30,
      y: height - 150,
      size: 12,
      font: timesRomanFont,
    });

    page.drawText(`${launchSupervisor}: ${launchNotes}`, {
      x: 30,
      y: height - 166,
      size: 12,
      font: timesRomanFont,
    });
  });

  // Get PDF file as a file Buffer
  const pdfBytes = await doc.save();

  // Return a PDF file with proper MIME type
  return { data: pdfBytes, contentType: "application/pdf" };
};
```

Note the format of the object that is returned from this code component:

```javascript
return { data: pdfBytes, contentType: "application/pdf" };
```

The return object specifies both a `data` property that is a file `Buffer`, and a `contentType` specifying the MIME type of the file being returned.

If we run a test again, we can see that a two-page PDF is being generated with formatted content from the webhook payload:

![Sample PDF output file from webhook payload](/assets/final-product.png)

## Further reading

That's it!
With just about 40 lines of code (if you omit comments and blank lines) we have a code component that renders PDFs.

For more information on code components checkout the [code component usage](/docs/composer/builder/components/code-component-usage) page.

---

## Building an Integration with Multiple Flows

In this tutorial we'll cover how to create an integration with multiple flows.
In this scenario, we are our fictional B2B software company, Progix.
Our customers would like to sync inventory and customer data from their "Acme ERP" systems into Progix.
Our integration to Acme ERP will be made up of three flows:

1. When customer data in Acme ERP is created or updated, the data is processed and sent to Progix.
1. When inventory data in Acme ERP is updated, that data processed and sent to Progix.
1. Acme ERP needs to be configured to send data to the previous two flows' webhook endpoints.
   A third flow runs at deploy-time and sets up webhooks within Acme ERP.

The first two flows _could_ be developed as distinct integrations, but then customer would need two instances deployed to them to integrate with Acme ERP (more as we handle more webhook types).
That would get get pretty burdensome.
It's much cleaner and maintainable to have a single "Acme ERP" integration that contains the various Acme ERP related flows.

## Creating our data sync flows

First we'll create a new integration.
When we're dropped into the Builder, we start with a flow that has the default name "Flow 1".
We can develop our first flow - the one that syncs customer data - in this editor.

When we're ready to add the second flow, we can click the **+ ADD FLOW** button on the top-left side of the integration designer area.

![Add flows to integration](/assets/add-flows.png)

We can call the new flow "Sync Inventory Data", and while we're at it we can rename "Flow 1" to "Sync Customer Data".

Each "Sync Data" flow can be developed as you would normally develop an integration.
You can read about developing integrations on the [building integrations](/docs/composer/builder/integrations/building-integrations) docs article.

### Config variables with multiple flows

Config variables are shared between flows.
That lets us enter Progix or Acme ERP authentication information just once when configuring an instance of the integration.
If we open up the **Configuration Wizard Designer** by clicking **Configuration Wizard**, we can customize the deployment experience for our consumers of the integration.
Let's go ahead and add headings and some config variables and that will be required for the various flows in the integration:

![Set config variables for multiple flows](/assets/config-wizard.png)

### Testing our data sync flows

Each flow has its own unique webhook URL and can be tested independently from the other flow.
To test a flow, we can swap over to the flow we'd like to test by clicking the name of the current flow on the top left of the Builder drawer, select the flow we'd like to test
Then, we can click **SAVE & RUN TEST**.

Running a test in one flow will not invoke the other flows.

## Create our initialization flow

At this point, we have two working flows that can process data from Acme ERP.
We could stop development here, and whenever we deploy an instance of this integration we could manually enter in the Webhook URLs that the instance is assigned into Acme ERP.

We'd like to create those webhooks programmatically, instead.
Let's create a third flow and call it "Initialization" that sets up those webhooks within Acme ERP.
Like last time, we'll add a new flow, and give it a name and description.

This time, though, select **Management Triggers** - **Instance Deploy** as your trigger:

![Select deploy trigger type](/assets/deploy-trigger.png)

### Referencing webhook URLs as inputs

Our "Initialization" flow will have two steps - one for each webhook we need to set up in Acme ERP to point to the two other "sync data" flows.
An integration is cognizant of its own flows' webhook URLs, and those are accessible from the trigger's `results.webhookUrls.FLOW_NAME`.
We can pass those webhook URLs as inputs into a component that is responsible for creating webhooks within Acme ERP:

We can test this flow as we would any other flow, and verify within Acme ERP that webhooks pointing to our test integration were set up as we'd expect.

---

## Configuration Driven Integration

In this quickstart we'll look at how you can use several types of config variables and connections to drive logic in your integration.
This helps to illustrate how your consumers can have instances of the same integration deployed to them, with different configurations.

## Basic config variables

The most basic type of config variable is a simple string.
A string config variable can have an optional default value, and you can add **Description** helper text to indicate to your end user what type of string the config variable expects.

For example, we can create a config variable that prompts the user for their API endpoint:

![Simple string config variable](/assets/simple-string-config-var.png)

When your user configures an instance of the integration, they're prompted for the string and they're provided the helper text you added:

![Simple string prompt](/assets/simple-string-prompt.png)

You can use the string that your user entered as an input for one or more steps:

![Simple string as input](/assets/simple-string-as-input.png)

Or, you can concatenate the string together with other static strings, config variables, and step results, to generate dynamic inputs for steps:

![Simple string in template](/assets/simple-string-in-template.png)

## Creating dropdown menus and branching from options

If you'd like to limit the options an end user can choose from, select **picklist** as your config variable data type.
You can generate a list of options that your user can choose from:

![Picklist config variable](/assets/picklist-config-var.png)

When deploying an instance of the integration, your user will see a dropdown menu with the options you created:

![Picklist input in the config wizard](/assets/picklist-config-wizard.png)

These config variables can be used like you use string config variables (above).

You can also drive branching logic from a picklist by adding a branch for each picklist option.

![Create a branch from a picklist](/assets/branch-from-picklist.png)

## Prompting for lists of values

Sometimes it's handy to have a user enter one or more values for a config variable (think "arrays" in JavaScript or "lists" in Python).
Create a config variable, and select **List** as the **Config Var Type**.

![List of strings in a config variable](/assets/list-config-var.png)

Users can enter one or more values for the config variable

![List config var in config wizard](/assets/list-config-wizard.png)

If you reference that config variable in steps of your integration, the code backing your step will receive an array of strings rather than a single string.

## Branching on boolean config variables

You may want to prompt a user with a "yes/no" question, and drive some logic based on their answer.
First, create a boolean input.

![Boolean type config variable](/assets/boolean-config-var.png)

The end user will see a simple toggle in their configuration wizard.

![Boolean in the config wizard](/assets/boolean-config-wizard.png)

Create a **Branch on Expression** step, and have one branch run if the value "is true" (otherwise, it'll follow the other branch)

![Branch based on boolean config var value](/assets/branch-on-boolean.png)

---

## Looping Over a Paginated API

When the number of records that an API stores is large, it's not economical to return all possible records at one time.
Instead, many APIs implement **pagination**.
That means that the API returns a small number of records at a time.
You as the consumer of the API can "page" through the records, and ask for more records by requesting the next "page".

In an integration it's often helpful to be able to loop over a paginated API.
In this tutorial, we'll look at how to use the loop component to loop over a paginated API.

## JSON Placeholder API

For illustration purposes, we'll use Typicode's [JSON Placeholder](https://jsonplaceholder.typicode.com/).
You can request all 100 "posts" in JSON Placeholder by making a request to https://jsonplaceholder.typicode.com/posts, and you can request fewer posts by making the same request with a `_limit` parameter.
You can also choose an offset by passing in a `_start` parameter.

For example, if you want just 10 posts, but you want to start at the 25th post, you can make a request to https://jsonplaceholder.typicode.com/posts?_limit=10&_start=25.

In this exercise we're going to page through all 100 posts, 10 at a time, so we'll be making a request to `/posts?_limit=10&_start=0`, then `/posts?_limit=10&_start=10`, `/posts?_limit=10&_start=20`, etc. until there are no more posts left to process.

:::note

With paginated APIs you often don't know how many total results exist. We happen to know that we're going to fetch 100 total "posts", but the looping strategy we cover here will accommodate any unknown number of posts. We'll simply loop until there are no more records left to loop over.
:::

## Our paginated integration

Our integration will follow this flow to process all posts in the paginated API:

- Start a loop
  - Fetch a page of up to 10 posts
  - Are we out of posts to process?
    - If so, break out of the loop
    - If not, loop over each post
      - Do something with the post (we'll just log out the post's title here)
      - Is this the last post?
        - If so, make a note of what `_start` we should use for the next loop iteration
  - Go back to the start of the loop

Let's get building!

### Our main loop

First, we'll create a Loop N Times loop step to loop over pages.
Under "Number of Iterations" we'll put in some high number, like 20, even though we'll break out of the loop before 20 iterations.

Having a maximum number of iterations in a loop helps guard against an infinite loop - we don't want to introduce unintended load on the vendor's API from an infinite loop.
If you know that you're going to loop over thousands of pages, you can choose a higher number of maximum iterations.

### Fetching a page of data

Next, we'll add two steps:

1. A Persist Data - Get Execution Value step will help to track the `_start` value in our API request.
   This action references a variable that is scoped to the current execution.
   That variable's value will be set by another step in the loop later.
   We'll provide a variable name, `Latest Post ID`, and default value `0` (since it's not been set yet):

 ![Persist Data - Get Execution Value](/assets/get-execution-value.png)

2. Next, we'll use the value from the previous step to make a call to JSON Placeholder.
   We'll add an HTTP - GET Request step and fetch `https://jsonplaceholder.typicode.com/posts?_limit=10&_start={{ THE VALUE WE GOT }}`:

![HTTP Get Request](/assets/get-posts.png)

### Are we done?

Next, we'll determine if we're done fetching posts.
We'll do this by adding a Branch on Expression step, and we'll check to see if the "Get Posts" step we invoked returned an empty array:

 ![Branch on Expression to Check Empty](/assets/branch-on-empty.png)

If the array returned was empty, we know there are no more results to page through.
In that case we'll add a Break Loop step to get out of our main loop:

 ![Break Loop](/assets/break-loop.png)

### Process posts

Assuming there are posts to process, we'll create an interior loop to loop over each post.

1. Add a Loop Over Items action that takes the results from the "Get Posts" step in order to loop over the results:

![Loop Over Items in integration designer](/assets/loop-over-posts.png)

1. We'll "process" each post.
   For illustration purposes we'll just log out the post's **id** and **title**.
   We can access each post's title by referencing the interior loop's `currentItem` property:

![Log Write Message](/assets/log-out-post.png)

### Store the last item's ID

Finally, we'll figure out the ID of the last post in the page we loaded, so we can adjust our `_start` parameter for the next loop.

1. We'll use a Branch on Expression action to determine if the `currentItem` has `isLast=true` (which indicates if we're looping over the last post):

![Branch on Expression to check for last post](/assets/is-last-post.png)

2. If we are on the last post, we'll use a Persist Data - Save Execution Value to save the ID of the last post.
   We'll use the same variable name - `Latest Post ID` - that we used before, and we'll save out the loop's `currentItem.id`.
   The "Get Execution Value" step we added at the beginning of the integration will pick up this value when the loop runs again:

![Persist Data - Save Execution Value](/assets/save-execution-value.png)

If we run our integration and look at logs, we can see that IDs and titles of the posts we loaded were logged out.
After every 10 posts (after post ID 60, 70, etc.) we can also see that that our main loop ran again and an additional page of posts was loaded.

## Pagination implementations

Different APIs implement their pagination differently.
Some page payloads contain a value indicating if you're on the last page or not.
Others contain a value to let you know what value to ask for with your next API call.
Your pagination loop implementation may look slightly different than this one, but hopefully this gave you a general idea of how to implement pagination in an integration.

---

## Looping Over Files in GCS Bucket

In this tutorial we will build an integration that downloads and processes files stored in Google Cloud Storage.

For this integration, assume that some third-party service writes a file to a Google Cloud Platform (GCP) storage bucket whenever an order is processed.

We'll configure our integration to run every five minutes, and our integration will do the following:

- Look for files in the `unprocessed/` directory of our GCP Storage bucket
- Loop over each file that we found:
  - Download the file
  - Deserialize the JSON contained in the file
  - Do some data mapping
  - Post the transformed data to an HTTP endpoint
  - Move the file from the `unprocessed/` directory to a `processed/` directory

Our integration will take advantage of the loop component to process files one by one.

:::note

If you do not have a Google Cloud Platform (GCP) account, you can use Dropbox, Box, Amazon S3, Azure Blob Storage, etc., instead.
They all have similar **list files**, **download file** and **move file** actions.

:::

## List files

We'll start by adding a Google Cloud Storage **List Files** action to our integration.
This will automatically create a Google Cloud Storage to our config wizard.
Under the **Bucket Name** input, we'll click **Config Variable** tab and create a new config variable to represent bucket name:

   ![Google Cloud Storage - List Files inputs](/assets/list-files-inputs.png)

Under **Prefix**, enter `unprocessed/`, so it only displays files in the `unprocessed/` directory of the bucket.

Next, we'll open the **Test Runner** drawer and select **Save & Reconfigure Test Instance** to set some test credentials.

   ![Google Cloud Storage - Test config variables](/assets/test-config-variables.png)

Finally, we'll click **Save & Run Test**.
If you see any errors about permissions, ensure that the Google IAM account you created as the proper permissions to the bucket you created.
You should see the files in your `unprocessed/` directory:

   ![Google Cloud Storage - List Files result](/assets/list-files-results.png)

## Create our loop

Next, we'll loop over the files that our **List Files** step found.
We'll add a **Loop Over Items** step.

Under the **Items** input we will reference the list of files our previous step returned:

   ![Loop Over Items](/assets/loop-step.png)

## Add tasks to the loop

Our loop is now configured to run once for each file that was found in the `unprocessed/` directory in our GCP bucket.
Our loop will contain a few steps to process and send the data to an external system:

### Download the file we're currently looping over

First, we'll download the file we're currently looping over.
The item that we're currently processing from our is accessible using the `currentItem` key of the loop.

We'll add a **Download File** action from the GCP component.

- For **File Name** we'll reference the loop's `currentItem`.
- For **Bucket Name** we'll reference the bucket name config variable we created.
- Our **Connection** is already set up for us.
  For example, if there's a file named `unprocessed/20210322_163522.json` in our bucket, `loopOverEachFile.currentItem` would be equal to `"unprocessed/20210322_163522.json"`:

 ![Download current file inputs](/assets/download-file-inputs.png)

Because we're downloading a JSON file, the JSON is automatically parsed for us.
If we'd downloaded an XML file, CSV, file, etc, we could have leveraged a Change Data Format step to deserialize the file.

   ![Download current file results](/assets/download-file-results.png)

### Map the data

Next, suppose the API we're sending the data to expects a different format ("quantity" instead of "qty", etc).
We can use the Collection Tools **Create Object** action to create a new object for us, referencing the results of the **Download File** step:

   ![Create object inputs](/assets/create-object-inputs.png)

### Send the data

Next, we'll use the HTTP component's **POST Request** action to send the data we generated.
As a placeholder for an external API, we'll post the data to [Postman's](https://www.postman.com/) endpoint.
For our **Data** input, we'll reference the **Create Object**'s results:

   ![HTTP POST inputs](/assets/http-post-inputs.png)

If we run **Save & Run Test** again, we can see the results of the POSTed data:

   ![HTTP POST results](/assets/http-post-results.png)

### Move the file to a processed directory

Finally, we'll move the file that we downloaded out of the way by moving the file from `unprocessed/` to `processed/`.

First, we need to replace the word `unprocessed` with `processed`.
We'll use the Text Manipulation component's **Find & Replace** action for that, once again referencing the loop's `currentItem`:

   ![Find-and-replace inputs](/assets/find-and-replace-inputs.png)

We'll add a Google Cloud Storage **Move File** action to move our folder from one folder to another:

   ![Move File inputs](/assets/move-file-inputs.png)

## Conclusion

That's it!
At this point we have an integration that loops over files in a directory, processes them, and sends the data to an HTTP endpoint.
This integration can be [published](/docs/composer/builder/integrations/overview#publishing-an-integration), and an integration can be configured and deployed.

---

## Composer

Composer is a vertical-specific commerce intelligence IPaaS. 

With Composer, you can:

- Choose from more than 100 available third-party integrations or build custom components.
- Take actions on connections to build your integrations (via managing specific API calls, functions and data inputs).
- And monitor every component via a single pane of glass.

Under the hood, Composer is made up of three core services, aimed at removing the operational challenges and risk associated with Composable Commerce architectures.

## Integrations Hub

Integrations Hub offers INSTANT-ON connections with market-leading technologies required to build Composable Commerce applications. These integrations include search, email, OMS, marketplace syndication, PIM, CRM, SSO, promotions, shipping and fulfillment, merchandising, translations, and more.

You can get started quickly and easily. Simply input your authentication credentials, enter the correct API endpoints from the third-party application, map data fields between the applications, and then go.

See [Integrations Hub](/docs/composer/integration-hub/integrations-hub).

## Builder

Builder provides a low code environment with more than 100 components and more than 3,000 possible actions available. Building new integrations from scratch has never been easier. Your developers can create functions and develop their own libraries of available integrations, and run them on a fully-managed cloud infrastructure. These components will inherit the operational management and underlying infrastructure of Composer.

You want the ability to offer unique commerce experiences to your customers. Rather than develop these components outside of a composable architecture and then assume the operational overhead and technical debt that comes along with maintaining this work in production, you can build your own integrations and receive native operational management, monitoring and performance delivery through Composer.

See [Builder](/docs/composer/builder/overview).

## Monitor

Monitor provides an aggregated view of all of your integration activities with visibility into each execution and the ability to drill into the details of any execution. Filter the logs or executions screens to look for failures across all integrations or filter down to a specific integration or even a specific process flow within a specific integration. Monitor acts as an operational control panel for your business, providing your DevOps teams with one central environment through which to view and manage your federated architectures.

See [Monitor](/docs/composer/monitor/logging).

---

## Integrating with Segment

You can quickly and easily integrate Commerce with Segment using the **Integrations Hub**. 

Segment is a customer data platform that simplifies the process of collecting data and connecting to new tools. With Segment, you can collect, transform, send, and archive your Commerce data, and send the data to your marketing, product, and analytics tools, including data warehouses. When there are customer or order changes in Commerce, Segment first processes the data, then translates and routes it to the destinations you have enabled in Segment. 

![segment diagram](/assets/segment_diagram.png)

The integration is responsible for server-side tracking, for example, order completion, updates, and cancellation events. Your business also requires a frontend component. For example, when customers view product details pages or when products are added to carts, you can integrate Segment Javascript in your frontend to track these events.

In other words, the integration enables you to track the stages of your customer's journey by integrating Commerce with Segment, using Commerce as the main source of information.

## Segment Integration Templates

The Segment Integration uses the following request templates that contain all parameters required for the Segment Integration to function correctly. The Segment Integration provides default templates. However, when configuring the integration, you can edit these templates to change or add any additional parameters that Segment provides, depending on your business requirements.

The templates use [JSONata](http://docs.jsonata.org/overview.html).

The following table describes the templates available.

| Template | Description |
| --- | --- |
| **Checkout Started Template** | If **Enable Checkout Started Tracking** is selected, you can use this template to define the information to send to Segment. A sample template is available [here](https://try.jsonata.org/I7eKN4Wjn). |
| **Order Completed Template** | If **Enable Order Completed Tracking** is selected, you can use this template to define the information to send to Segment. A sample template is available [here](https://try.jsonata.org/qKuCE2Tgr). |
| **Order Updated Template** | If **Enable Order Updated Tracking** is selected, you can use this template to define the information to send to Segment. A sample template is available [here](https://try.jsonata.org/qVyeWzjLd). |
| **Order Refunded Template** | If **Enable Order Updated Tracking** is selected, you can use this template to define the information to send to Segment. A sample template is available [here](https://try.jsonata.org/CkaB6SRcT). |
| **Order Cancelled Template** | If **Enable Order Cancelled Tracking** is selected, you can use this template to define the information to send to Segment. A sample template is available [here](https://try.jsonata.org/xJyM0nuPY). |
| **Customer Created Template** | If **Enable Customer Created Tracking** is selected, you can use this template to define the information to send to Segment. A sample template is available [here](https://try.jsonata.org/u_8GxyXVX). |
| **Customer Updated Template** | If **Enable Customer Updated Tracking** is selected, you can use this template to define the information to send to Segment. A sample template is available [here](https://try.jsonata.org/u_8GxyXVX). |

## Collecting Your Integration Setup Information

Before you configure the integration in Commerce Manager, you need to collect the necessary setup information from Segment and Commerce Manager.

### Collecting Segment Connection Details

You can find this information in **Settings**.

| Option | Description |
| --- | -- |
| **Host** |  Your Segment API host. Default is `https://api.segment.io`. |
| **Path** | Default is `/v1/batch`. |
| **Write Key** | A unique identifier for your Commerce source. See [Find your write key](https://segment.com/docs/getting-started/02-simple-install/#find-your-write-key). |

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. When you log in to Commerce Manager as a Seller Admin, you can find this information in **SYSTEM** > **Application Keys** in Commerce Manager.

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

| Option            | Description                                                                                                                             |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| **Client ID**     | Your Commerce Client ID.                                                                                                                |
| **Client Secret** | Your Commerce Client Secret.                                                                                                            |
| **Token URL**     | Your Commerce API Base URL. EU - `https://euwest.api.elasticpath.com/`US - `https://useast.api.elasticpath.com/` |

## Configuring Segment Integration

1. In Commerce Manager, go to **COMPOSER > Integrations Hub**.
2. Under **Customer Management**, click **Segment**. 
3. Click **Configure**. The Avalara integration guides you through the steps you need to follow to complete the integration.
4. Click **Next**. The **Connections** page is displayed.
5. Enter the following details in **Commerce Connection**:
   - **Client-ID**  - Your Commerce Client ID.
   - **Client-Secret** - Your Commerce Client Secret.
   - **Token URL** - Your Commerce API Base URL. For example, `https://euwest.cm.elasticpath.com`.
6. Click **Connect**. The authorization is successfully completed.
7. Enter the following details in **Segment Connection**:
    - **Client ID** - Your Segment API host. Default is `https://api.segment.io`.
    - **Path** - Default is `/v1/batch`.
    - **Write Key** - A unique identifier for your Commerce source. See [Find your write key](https://segment.com/docs/getting-started/02-simple-install/#find-your-write-key).
8. Click **Next**. The **Configurations** pane is displayed.
9. Select the Commerce data you want collect in Segment. See [Observable Events](/docs/api/integrations/integrations-introduction#observable-events).

    For **Order Tracking Configuration** 

    | Option                               | Description                                                                                                        |
    |--------------------------------------|--------------------------------------------------------------------------------------------------------------------|
    | **Enable Checkout Started Tracking** | By default, `order.created` events are tracked. Alternatively, you might want to select `order.authorized` events. |
    | **Enable Order Completed Tracking**  | By default, `order.paid` events are tracked. Alternatively, you might want to select `order.fulfilled` events.     |
     | **Enable Order Updated Tracking**    | By default, `order.updated` events are tracked.                                                                                                                |
    | **Enable Order Refunded Tracking** | By default, `order.refunded` events are tracked. |
    | **Enable Order Cancelled Tracking** | By default, `order.cancelled` events are tracked. |

   For **Customer Tracking Configuration**

    | Option | Description |
    | --- | --- |
    | **Enable Customer Created Tracking** | By default, `customer.created` events are tracked.  |
    | **Enable Customer Updated Tracking** | By default, `customer.updated` events are tracked. Alternatively, you might want to select `customer.deleted` events. |

10. Click **Next**. The **Templates** pane is displayed. See [Segment Integration Templates](#segment-integration-templates).
11. Click **Finish**. Your integration is enabled.

Once your integration is enabled, the events you have configured are automatically sent to Segment. 

![segment integration enabled](/assets/segment_integration_enabled.png)

---

## Kount 360 Integration API Reference

This document provides detailed API reference information for all endpoints exposed by the Kount Fraud Evaluation Integration.

## Overview

The Kount Fraud Evaluation Integration exposes two main endpoints:

1. **Risk Evaluation API** - Synchronous endpoint for fraud risk assessment
2. **Order Fulfillment Webhook** - Asynchronous webhook handler for order status updates

All endpoints return JSON responses and use standard HTTP status codes for error handling.

### Base URLs

Integration endpoints are region-specific:

- **US East**: `https://hooks.us-east-2.elasticpathintegrations.com`
- **EU West**: `https://hooks.eu-west-1.elasticpathintegrations.com`

**Important**: Actual endpoint URLs include encoded flow configuration IDs that are generated during integration deployment. Obtain the complete URLs from your Prismatic integration instance.

---

## Authentication

### API Key Authentication

The Risk Evaluation Flow should be secured with an API key generated during instance configuration.

**Header**: `x-api-key: {your_api_key}`

### Webhook Authentication

Webhook endpoints, such as the Order Fulfillment Flow use EPCC's standard webhook authentication.  The following security header is automatically sent by Elastic Path Commerce Cloud when it invokes the configured webhook.

**Header**: `x-moltin-secret-key: {webhook_secret}`

The webhook secret is configured during integration setup and must match the value configured in EPCC.  The integration attempts to configure this secret automatically during integration instance creation.

---

## Risk Evaluation API

### Endpoint

```
POST /trigger/{flowId}
```

**Type**: Synchronous
**Format**: JSON

### Purpose

Evaluates fraud risk for an EPCC cart before checkout completion. This endpoint:

1. Retrieves cart data from EPCC
2. Transforms cart to Kount order format
3. Sends order to Kount for risk evaluation
4. Stores Kount order ID in EPCC cart custom attributes
5. Returns risk decision and score

### Request Format

#### Headers

```http
Content-Type: application/json
x-api-key: {your_api_key}
```

#### Request Body

```json
{
  "cartId": "d121ea2210434ffc8a90daff9cc97e76",
  "orderNumber": "ORD-2024-001234",
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "New York",
    "region": "NY",
    "postalCode": "10001",
    "countryCode": "US",
    "phoneNumber": "+1-555-123-4567"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "line1": "456 Oak Avenue",
    "city": "New York",
    "region": "NY",
    "postalCode": "10002",
    "countryCode": "US",
    "phoneNumber": "+1-555-123-4567"
  },
  "deviceSessionId": "abc123def456ghi789jkl",
  "userIp": "192.168.1.100",
  "customFields": {
    "merchantId": "12345",
    "campaignId": "summer2024"
  },
  "riskInquiry": true,
  "channelIdentifier": "WEB",
  "fulfillmentType": "SHIPPED"
}
```

#### Required Fields

:::caution

The [cart should have the `contact.email` field set](https://developer.elasticpath.com/docs/api/carts/update-a-cart#request) for an email to be attached to the Kount 360 Order and evaluated as part of the fraud decision.

:::

| Field | Type | Description |
|-------|------|-------------|
| `cartId` | string | EPCC cart identifier |
| `orderNumber` | string | Merchant order number (used as Kount merchant order ID) |
| `billingAddress` | object | Customer billing address |
| `userIp` | string | Customer IP address (IPv4 format) |

#### Optional Fields

| Field | Type | Description | Default |
|-------|------|-------------|---------|
| `shippingAddress` | object | Shipping address (uses cart shipping groups if not provided) | From cart |
| `deviceSessionId` | string | Kount device session identifier | null |
| `customFields` | object | Additional merchant-specific data | {} |
| `riskInquiry` | boolean | Enable immediate risk evaluation | Configuration default |
| `channelIdentifier` | string | Channel identifier for order classification | Configuration default |
| `fulfillmentType` | string | Fulfillment method | Configuration default |

#### Address Object Format

```json
{
  "firstName": "John",
  "lastName": "Doe",
  "company": "Acme Corp",
  "line1": "123 Main Street",
  "line2": "Apt 4B",
  "city": "New York",
  "region": "NY",
  "postalCode": "10001",
  "countryCode": "US",
  "phoneNumber": "+1-555-123-4567"
}
```

### Response Format

#### Success Response (200 OK)

```json
{
  "decision": "APPROVE",
  "score": 85.5,
  "kountOrderId": "B2C3D4F6G7H8J10K",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "processingTimeMs": 1250,
  "fallback": false
}
```

#### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `decision` | string | Risk decision: `APPROVE`, `DECLINE`, or `REVIEW` |
| `score` | number | Risk score (0-100, higher = safer) |
| `kountOrderId` | string | Kount order identifier for tracking |
| `correlationId` | string | Request correlation ID for debugging |
| `processingTimeMs` | integer | Processing time in milliseconds |
| `fallback` | boolean | Whether fallback decision was used |
| `fallbackReason` | string | Reason for fallback (if applicable) |

### Error Responses

#### Validation Error (200)

```json

{
  "name": "IntegrationError",
  "code": "VALIDATION_ERROR",
  "correlationId": "",
  "timestamp": "2025-08-26T20:11:48.187Z"
}
```

#### Cart Empty (200)

```json
{
  "name": "IntegrationError",
  "code": "INTERNAL_ERROR",
  "correlationId": "kount-1756239042367-65b3f15f-d5b0-4c70-b223-b5a318036e2c",
  "timestamp": "2025-08-26T20:10:43.155Z",
  "details": "risk_evaluation_failed",
  "originalError": {
    "code": "CART_EMPTY"
  }
}
```

#### Internal Server Error (200)

```json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal processing error occurred",
    "correlationId": "kount-20241201-123456-uuid",
    "timestamp": "2024-12-01T10:30:00Z"
  }
}
```

---

## Order Fulfillment Webhook

### Endpoint

```
POST /webhook/order-fulfilled
```

**Type**: Asynchronous
**Format**: JSON
**Security**: EPCC webhook secret validation

### Purpose

Processes EPCC `order.fulfilled` webhook events and updates Kount with order fulfillment status. This webhook:

1. Validates EPCC webhook authentication
2. Extracts order fulfillment information
3. Updates Kount with fulfillment status
4. Returns processing confirmation

### Request Format

#### Headers

```http
Content-Type: application/json
x-moltin-secret-key: {webhook_secret}
```

#### Request Body

EPCC automatically sends webhook payloads in the following format:

```json
{
  "id": "1cb8697d-d13a-4cda-94e2-5b1881c877cd",
  "triggered_by": "order.fulfilled",
  "attempt": 1,
  "integration": {
    "id": "a13b32fd-cb8c-4adf-9f71-de830b8d777a",
    "integration_type": "webhook",
    "name": "Kount Fraud Detection"
  },
  "payload": {
    "data": {
      "id": "45936d34-7ce7-48fd-9673-eae9b434dd5e",
      "type": "order",
      "status": "complete",
      "payment": "paid",
      "shipping": "fulfilled",
      "order_number": "ORD-2024-001234",
      "shipping_tracking_number": "1Z999999999999999",
      "shipping_tracking_url": "https://tracking.example.com/1Z999999999999999",
      "custom_attributes": {
        "kountOrderId": {
          "type": "string",
          "value": "B2C3D4F6G7H8J10K"
        }
      },
      "meta": {
        "timestamps": {
          "created_at": "2024-12-01T10:00:00Z",
          "updated_at": "2024-12-01T11:00:00Z"
        }
      }
    }
  }
}
```

### Response Format

NOTE: This is an asynchronous flow which always replies with an HTTP 200 code and an execution id that can be used to monitor or lookup the final results.  The following error messages would be visible in logs for the execution flow.

#### Success Response 

```json
{
  "status": "success",
  "message": "Order fulfillment status updated successfully",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-12-01T10:30:00Z",
  "processingTimeMs": 450,
  "kountOrderId": "B2C3D4F6G7H8J10K"
}
```

### Error Responses

#### Invalid Webhook Secret (401 Unauthorized)

```json
{
  "code": "INVALID_WEBHOOK_SECRET",
  "message": "Webhook authentication failed",
  "correlationId": "kount-20241201-123456-uuid",
  "timestamp": "2024-12-01T10:30:00Z"
}
```

#### Validation Error (400 Bad Request)

```json
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid webhook payload structure",
  "details": "Missing required field: payload.data.id",
  "correlationId": "kount-20241201-123456-uuid",
  "timestamp": "2024-12-01T10:30:00Z"
}
```

---

## Error Handling

### Error Code Reference

| Code | Description | HTTP Status | Recommended Action |
|------|-------------|-------------|-------------------|
| `VALIDATION_ERROR` | Request validation failed | 400 | Fix request format/data |
| `CART_EMPTY` | EPCC cart not found | 404 | Verify cart ID exists |
| `KOUNT_API_ERROR` | Kount service error | 500 | Retry request, check Kount status |
| `EPCC_API_ERROR` | EPCC service error | 500 | Retry request, check EPCC status |
| `NETWORK_ERROR` | Network connectivity issue | 500 | Retry with backoff |
| `INTERNAL_ERROR` | Internal processing error | 500 | Contact support with correlation ID |
| `INVALID_WEBHOOK_SECRET` | Webhook authentication failed | 401 | Verify webhook secret configuration |
| `KOUNT_ORDER_NOT_FOUND` | Kount order not found | 404 | Verify Kount order exists |

### Error Response Format

All errors follow a consistent format:

```json
{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": "Additional error context (optional)",
  "correlationId": "UUID for tracking",
  "timestamp": "ISO 8601 timestamp"
}
```

### Kount Retry Guidelines

- **Rate Limit Errors**: 429 response code triggers a retry with exponential backoff with configurable delay and attempts

---

## SDK Examples

### JavaScript/Node.js

#### Risk Evaluation Request

```javascript
const axios = require('axios');

const evaluateRisk = async (cartData) => {
  try {
    const response = await axios.post(
      'https://hooks.us-east-2.elasticpathintegrations.com/trigger/YOUR_FLOW_ID',
      {
        cartId: cartData.cartId,
        orderNumber: cartData.orderNumber,
        billingAddress: cartData.billingAddress,
        shippingAddress: cartData.shippingAddress,
        userIp: cartData.userIp,
        deviceSessionId: cartData.deviceSessionId,
        riskInquiry: true
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${process.env.PRISMATIC_API_KEY}`
        },
        timeout: 10000
      }
    );

    return response.data;
  } catch (error) {
    console.error('Risk evaluation failed:', error.response?.data || error.message);
    throw error;
  }
};

// Example usage
const cartData = {
  cartId: 'd121ea2210434ffc8a90daff9cc97e76',
  orderNumber: 'ORD-2024-001234',
  billingAddress: {
    firstName: 'John',
    lastName: 'Doe',
    line1: '123 Main Street',
    city: 'New York',
    region: 'NY',
    postalCode: '10001',
    countryCode: 'US'
  },
  shippingAddress: {
    firstName: 'John',
    lastName: 'Doe',
    line1: '456 Oak Avenue',
    city: 'New York',
    region: 'NY',
    postalCode: '10002',
    countryCode: 'US'
  },
  userIp: '192.168.1.100',
  deviceSessionId: 'abc123def456'
};

evaluateRisk(cartData)
  .then(result => {
    console.log('Risk Decision:', result.decision);
    console.log('Risk Score:', result.score);
    console.log('Kount Order ID:', result.kountOrderId);
  })
  .catch(error => {
    console.error('Error:', error);
  });
```

### Python

#### Risk Evaluation Request

```python
import requests
import json
from typing import Dict, Any

def evaluate_risk(cart_data: Dict[str, Any], api_key: str, flow_id: str) -> Dict[str, Any]:
    """
    Evaluate fraud risk for a cart using the Kount integration.
    
    Args:
        cart_data: Cart and customer information
        api_key: Prismatic API key
        flow_id: Integration flow ID
    
    Returns:
        Risk evaluation response
    """
    url = f"https://hooks.us-east-2.elasticpathintegrations.com/trigger/{flow_id}"
    
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {api_key}'
    }
    
    payload = {
        'cartId': cart_data['cart_id'],
        'orderNumber': cart_data['order_number'],
        'billingAddress': cart_data['billing_address'],
        'shippingAddress': cart_data.get('shipping_address'),
        'userIp': cart_data['user_ip'],
        'deviceSessionId': cart_data.get('device_session_id'),
        'riskInquiry': True
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload, timeout=30)
        response.raise_for_status()
        return response.json()
    
    except requests.exceptions.RequestException as e:
        print(f"Risk evaluation failed: {e}")
        if hasattr(e, 'response') and e.response is not None:
            print(f"Error details: {e.response.json()}")
        raise

# Example usage
cart_data = {
    'cart_id': 'd121ea2210434ffc8a90daff9cc97e76',
    'order_number': 'ORD-2024-001234',
    'billing_address': {
        'firstName': 'John',
        'lastName': 'Doe',
        'line1': '123 Main Street',
        'city': 'New York',
        'region': 'NY',
        'postalCode': '10001',
        'countryCode': 'US'
    },
    'user_ip': '192.168.1.100',
    'device_session_id': 'abc123def456'
}

try:
    result = evaluate_risk(cart_data, 'your_api_key', 'your_flow_id')
    print(f"Risk Decision: {result['decision']}")
    print(f"Risk Score: {result['score']}")
    print(f"Kount Order ID: {result['kountOrderId']}")
except Exception as e:
    print(f"Error: {e}")
```

### cURL

#### Risk Evaluation Request

```bash
curl -X POST \
  https://hooks.us-east-2.elasticpathintegrations.com/trigger/YOUR_FLOW_ID \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "cartId": "d121ea2210434ffc8a90daff9cc97e76",
    "orderNumber": "ORD-2024-001234",
    "billingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "line1": "123 Main Street",
      "city": "New York",
      "region": "NY",
      "postalCode": "10001",
      "countryCode": "US"
    },
    "userIp": "192.168.1.100",
    "deviceSessionId": "abc123def456",
    "riskInquiry": true
  }'
```

### Integration Patterns

#### Error Handling with Fallback

```javascript
const evaluateRiskWithFallback = async (cartData) => {
  try {
    const result = await evaluateRisk(cartData);
    
    // Check if fallback decision was used
    if (result.fallback) {
      console.warn(`Fallback decision used: ${result.fallbackReason}`);
      // Implement additional logging or monitoring
    }
    
    return result;
  } catch (error) {
    // Implement fallback logic for critical errors
    if (response?.code) {
      console.error('Service unavailable, using local fallback');
      return {
        decision: 'REVIEW', // Safe default
        score: 0,
        kountOrderId: null,
        fallback: true,
        fallbackReason: 'Service unavailable'
      };
    }
    
    throw error;
  }
};
```

---

## OpenAPI Specifications

Complete OpenAPI specifications are available:

- **Risk Evaluation API**: [`OpenAPI Specification YAML`](/assets/composer/kount360/risk-evaluation-api.yaml)
- **Order Fulfillment Webhook**: [`OpenAPI Specification YAML`](/assets/composer/kount360/order-fulfillment-webhook-api.yaml)

These specifications can be used with API development tools like Postman, Insomnia, or Swagger UI for testing and integration development.

---

## Kount 360 Integration Configuration Reference

This guide provides detailed instructions for configuring the Kount Fraud Evaluation Integration.

## Prerequisites

Before configuring the integration, ensure you have:

### EPCC Requirements

- **Store Access**: Active EPCC store with admin access in Commerce Manager
- **API Credentials**: Client credentials for OAuth authentication

### Kount Requirements

- **Kount 360 Account**: Active account with API access enabled
- **OAuth2 Credentials**: API key for authentication
- **Merchant Configuration**: Configured merchant settings in Kount portal
- **Environment Access**: Production or sandbox environment credentials

---

## Connection Configuration

### Create a new Integration Instance

1. In Commerce Manager, click on Composer in the left nav.
2. Locate and click on the **Kount Fraud Evaluation** integration
3. Click on **Configure**
4. Details on how to configure each field are provided in the sections below.
5. Click on **Finish** on the final configuration page to create your integration instance.

### EPCC Connection

The EPCC connection uses OAuth2 client credentials flow.

#### Required Fields

| Field | Description | Example |
|-------|-------------|---------|
| **Client ID** | EPCC application client ID | `your_epcc_client_id` |
| **Client Secret** | EPCC application client secret | `your_epcc_client_secret` |
| **Token URL** | EPCC OAuth token endpoint | `https://useast.api.elasticpath.com/oauth/access_token` |
| **Throttle Limit** | API rate limit (requests per interval) | `3` |
| **Throttle Interval** | Rate limit interval in milliseconds | `125` |
| **Keep Alive Flag** | Enable connection keep-alive | `true` |
| **Keep Alive Interval** | Keep-alive interval in milliseconds | `10000` |

#### Token URL Options

- **US East**: `https://useast.api.elasticpath.com/oauth/access_token`
- **EU West**: `https://euwest.api.elasticpath.com/oauth/access_token`

#### Configuration Steps

- Configure the **Elastic Path Composable Commerce Connection**:
  - Enter your EPCC Client ID
  - Enter your EPCC Client Secret
  - Select the appropriate Token URL for your region
  - Configure throttling settings
  - Enable keep-alive settings for optimal performance

### Kount Connection

The Kount connection uses OAuth2 with API key authentication.

#### Required Fields

| Field | Description | Example |
|-------|-------------|---------|
| **API Key** | Kount API key for authentication | `your_kount_api_key` |
| **Token URL** | Kount OAuth2 token endpoint | `https://login.kount.com/oauth2/ausdppksgrbyM0abp357/v1/token` |
| **Base URL** | Kount API base URL | `https://api.kount.com/commerce` |
| **OAuth Scope** | OAuth scope for API access | `k1_integration_api` |
| **Retry Attempts** | Maximum retry attempts for failed calls | `3` |
| **Retry Delay** | Initial retry delay in milliseconds | `1000` |
| **Request Timeout** | Request timeout in seconds (max 30) | `15` |

#### Environment URLs

**Production**:
- Token URL: `https://login.kount.com/oauth2/ausdppksgrbyM0abp357/v1/token`
- Base URL: `https://api.kount.com/commerce`

**Sandbox**:
- Token URL: `https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token`
- Base URL: `https://api-sandbox.kount.com/commerce`

#### Configuration Steps

- Configure the **Kount Connection**:
  - Enter your Kount API Key (obtained from Kount portal)
  - Select the appropriate Token URL for your environment
  - Select the corresponding Base URL
  - Use default OAuth scope unless instructed otherwise by Kount
  - Configure retry and timeout settings based on your performance requirements

---

## Integration Settings

These settings control the behavior and security of the integration.

### Webhook Security

| Setting | Description | Default | Notes |
|---------|-------------|---------|-------|
| **Webhook Secret Key** | Secret key for EPCC webhook validation | Auto-generated UUID | Automatically generated if not provided |

**Configuration**: The webhook secret is auto-generated during deployment. You can provide a custom value if required by your security policies.

### Logging Configuration

| Setting | Description | Options | Default |
|---------|-------------|---------|---------|
| **Log Level** | Verbosity of integration logging | `error`, `warn`, `info`, `debug`, `trace` | `error` |

**Usage Guidelines**:
- **Production**: Use `error` or `warn` for optimal performance
- **Development**: Use `warn` unless detailed troubleshooting is needed, then use `debug`
- **Testing**: Use `debug` for comprehensive request/response logging

### Risk Evaluation Settings

| Setting | Description | Options | Default |
|---------|-------------|---------|---------|
| **Fallback Decision** | Decision when Kount is unavailable | `APPROVE`, `DECLINE`, `REVIEW` | `REVIEW` |
| **Enable Risk Inquiry** | Enable immediate risk evaluation | `true`, `false` | `true` |

**Fallback Decision Guidelines**:
- **APPROVE**: Use for low-risk environments where service availability is critical
- **DECLINE**: Use for high-security environments where fraud prevention is paramount
- **REVIEW**: Recommended default for manual review workflows

### Webhook Management

| Setting | Description | Options | Default |
|---------|-------------|---------|---------|
| **Cleanup Webhooks on Delete** | Auto-remove EPCC webhooks when instance is deleted | `true`, `false` | `true` |

---

## Business Configuration

These settings define the business rules and channel configuration for fraud evaluation.

### Channel Configuration

| Setting | Description | Example | Default |
|---------|-------------|---------|---------|
| **Channel Identifier** | Channel identifier sent to Kount when none specified. | `WEB_CHECKOUT`, `MOBILE_APP`, `CALL_CENTER` | `WEB_CHECKOUT` |

### Fulfillment Configuration

| Setting | Description | Options | Default |
|---------|-------------|---------|---------|
| **Default Fulfillment Type** | Fulfillment method when none specified | `SHIPPED`, `DIGITAL`, `STORE_PICK_UP`, `LOCAL_DELIVERY`, `STORE_DRIVE_UP`, `IN_PERSON` | `SHIPPED` |
| **Default Shipping Provider** | Shipping provider name used when none specified. | `UPS`, `FedEx`, `USPS`, `FBM`, `Other` | `FedEx` |
| **Default Shipping Method** | Shipping speed/method when none specified. | `STANDARD`, `EXPRESS`, `SAME_DAY`, `NEXT_DAY`, `SECOND_DAY` | `STANDARD` |

**Configuration Guidelines**:
- **Fulfillment Type**: Should match your primary fulfillment method
- **Shipping Provider**: Use the most common carrier for your orders
- **Shipping Method**: Default to your standard shipping option

---

### Webhook Configuration

The integration automatically configures EPCC webhooks during deployment:

- **Event**: `order.fulfilled`
- **URL**: Dynamically generated by Integrations Hub
- **Authentication**: Uses configured webhook secret key
- **Retry**: No automatic retry.  Webhooks can be redelivered using the Integrations Hub execution viewer.

---

## Troubleshooting
#### Connection Problems

**EPCC Connection Failures**:
- Verify client ID and secret are correct
- Check token URL matches your EPCC region
- Ensure API credentials have required permissions
- Verify network connectivity to EPCC endpoints

**Kount Connection Failures**:
- Confirm API key is active in Kount portal
- Verify token URL matches your environment (production/sandbox)
- Check OAuth scope is correct
- Ensure Kount account has API access enabled

#### Webhook Issues

**Webhook Not Receiving Events**:
- Verify webhook secret matches configuration
- Check EPCC webhook configuration in Commerce Manager
- Review webhook delivery logs in EPCC

**Authentication Failures**:
- Confirm webhook secret key configuration
- Check `x-moltin-secret-key` header in webhook requests
- Verify webhook secret hasn't been modified

### Support Resources

- **Integration Logs**: Available in the Integration Details section of Composer in Commerce Manager dashboard
- **API Documentation**: See [API Reference](./kount-api-ref.md)
- **Kount Documentation**: See [Kount 360 Integration Guide](https://developer.kount.com/hc/en-us/articles/14474979202068-Payments-Fraud-v2-0-Integration-Guide)
- **Kount API Reference**: See [Commerce APIs](https://api.kount.com/commerce/help)

---

## Kount 360 Integration Overview

The **Kount Fraud Evaluation** Integration is an Integrations Hub Integration that provides real-time fraud detection for EPCC application clients (i.e. storefronts, AI agents) using Kount's risk evaluation services. This integration enables:

- **Pre-checkout risk assessment** - Evaluate fraud risk before order completion
- **Automated order fulfillment updates** - Sync fulfillment status with Kount for improved accuracy
- **Configurable business rules** - Customize fallback decisions when Kount is unavailable
- **Comprehensive error handling** - Robust error management with detailed logging

### Key Capabilities

- **Synchronous risk evaluation** during checkout flow
- **Asynchronous order fulfillment tracking** via webhooks
- **Automatic webhook management** during instance lifecycle
- **Configurable fallback decisions** when Kount services are unavailable
- **Request correlation tracking** for debugging and monitoring

---

## Architecture

The integration consists of three main flows:

### 1. Init Flow (Deployment)
- **Type**: Asynchronous lifecycle flow
- **Purpose**: Manages integration instance deployment and deletion
- **Actions**: 
  - Configures EPCC webhooks for order fulfillment tracking
  - Cleans up webhooks during instance deletion

### 2. Risk Evaluation Flow
- **Type**: Synchronous API endpoint
- **Purpose**: Evaluates fraud risk for carts before checkout
- **Actions**:
  - Retrieves EPCC cart data with line items
  - Transforms cart to Kount order format
  - Sends order to Kount for risk evaluation
  - Stores Kount order ID and fulfillment mappings in EPCC cart
  - Returns risk decision and score

### 3. Order Fulfillment Flow
- **Type**: Asynchronous webhook handler
- **Purpose**: Updates Kount with order fulfillment status
- **Actions**:
  - Validates EPCC webhook security
  - Processes `order.fulfilled` events
  - Updates Kount with fulfillment status changes

---

## Prerequisites

### EPCC Requirements
- **EPCC Store**: Active Elastic Path Commerce Cloud store
- **API Credentials**: Client ID and Secret with appropriate permissions
- **Store Configuration**: Access to webhook management

### Kount Requirements
- **Kount Account**: Active Kount 360 account
- **API Access**: OAuth2 credentials for Kount API
- **Integration Setup**: Configured merchant settings in Kount portal

### Prismatic Platform
- **Integrations Hub**: Access to Integrations Hub
- **Instance Management**: Permissions to deploy and configure integrations

---

## Flow Reference

| Flow Name | Endpoint Type | Synchronous | Purpose |
|-----------|---------------|-------------|---------|
| **Init Flow** | Lifecycle | No | Instance deployment/deletion management |
| **Risk Evaluation Flow** | REST API | Yes | Real-time fraud risk assessment |
| **Order Fulfillment Flow** | Webhook | No | Order status synchronization |

### Flow Relationships

```mermaid
graph TB
    A[Storefront] -->|POST| B[Risk Evaluation Flow]
    B -->|Query| C[EPCC Cart API]
    B -->|Evaluate| D[Kount API]
    B -->|Update| C
    
    E[EPCC Order Fulfillment] -->|Webhook| F[Order Fulfillment Flow]
    F -->|Update| D
    
    G[Integration Deployment] -->|Lifecycle| H[Init Flow]
    H -->|Configure| E
```

---

## Configuration

The integration requires configuration across three main areas:

### Connection Configuration
- **EPCC Connection**: OAuth2 client credentials for EPCC API access
- **Kount Connection**: OAuth2 credentials and API settings for Kount services

### Integration Settings
- **Webhook Security**: Auto-generated secret key for EPCC webhook validation
- **Logging Level**: Configurable logging verbosity (error, warn, info, debug, trace)
- **Risk Evaluation**: Enable/disable immediate risk inquiry
- **Fallback Decisions**: Default decision when Kount is unavailable

### Business Configuration
- **Channel Settings**: Identifier sent to Kount for order classification
- **Fulfillment Defaults**: Default fulfillment type, shipping provider, and method

For detailed configuration instructions, see: [Configuration Guide](./kount-config-ref.md)

---

## API Reference

### Risk Evaluation API
- **Method**: POST
- **Type**: Synchronous
- **Purpose**: Evaluate cart fraud risk before checkout
- **Authentication**: X-API-key header, generated during configuration

### Order Fulfillment Webhook
- **Method**: POST  
- **Type**: Asynchronous
- **Purpose**: Process EPCC order fulfillment events
- **Authentication**: EPCC webhook secret validation

For complete API documentation, see: [API Reference](.//kount-api-ref.md)

---

## Getting Started

1. **Review Prerequisites**: Ensure you have the required EPCC store, Kount account, and Prismatic access
2. **Configure Connections**: Set up EPCC and Kount API credentials
3. **Create Integration Instance**: Create and configure the integration instance
4. **Test Integration**: Verify risk evaluation and webhook functionality
5. **Go Live**: Enable production traffic through the integration

---

## Support and Troubleshooting

### Logging and Monitoring
- All requests include correlation IDs for tracing
- Configurable log levels for debugging
- Processing time tracking for performance monitoring

### Error Handling
- Comprehensive error classification codes
- Fallback decisions for service unavailability
- Detailed error messages with correlation tracking

### Common Issues
- **Webhook Authentication**: Verify webhook secret configuration
- **API Timeouts**: Check network connectivity and API limits  
- **Missing Cart Data**: Ensure required cart fields are populated
- **Kount Configuration**: Verify merchant settings in Kount portal

For specific configuration details, refer to the [Configuration Guide](.//kount-config-ref.md) and [API Reference](./kount-api-ref.md).

---

## Overview(Integration-hub)

You can integrate Commerce quickly and easily using the **Integrations Hub** in Commerce Manager. Integrations allow you to integrate with third-party providers, such as site search integrations, with just a few clicks. 

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/cA5u83mlQmk" title="Integrations Hub - Build and Editing Deep Dive" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with Braze

You can quickly and easily integrate Commerce with Braze using the **Integrations Hub** in Commerce Manager. Integrating with Braze allows you to send customer profile information of Commerce to the Braze platform. Additionally, this integration allows a user to declare how the data from Commerce is mapped to Braze endpoints.

![Braze Integration](/assets/Braze-integration.png)

:::note
When integrating with third party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Prerequisites

- Ensure that you have collected your **Client-ID** and **Client-Secret** from Commerce Manager. See [Application Keys](/docs/commerce-manager/application-keys/application-keys-cm).
- Ensure that you have received a URI from Braze to interact with the Braze services once you have registered as a Braze customer.
- Ensure that you have created your Braze API Key. The following procedure describes how to create your API key:

    1. Log into Braze. 
    1. Under **SETTINGS**, click **Developer Console**.
    1. Go to **API Settings** tab.
    1. Under **Rest API Keys** section, click **+Create New API Key**.
    1. In the **API Key Name** field, enter a name for your API key.
    1. To set minimum permissions for this integration, select **users.track**, **users.delete**, and **email.status** checkboxes.
    1. Click **Save API Key**.
    
        A list of your API keys will be displayed once you have saved your new API key. Copy your created API Key from the list.

## Configuring Braze Integration

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Marketing & Communication**, click **Braze**. The integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** consist of some details about the integration.
1. Click **Next**. The **Configuration** page is displayed.
1. Enter the following details in **Commerce Connection**:
    - **Client-ID**  - Your Commerce Client ID.
    - **Client-Secret** - Your Commerce Client Secret.
    - **Token URL** - Your Commerce API Token URL.

    **Token URL** for:
    - EU - `https://useast.api.elasticpath.com/oauth/access_token`
    - US - `https://useast.api.elasticpath.com/oauth/access_token`

1. Click **Connect**. The authorization is successfully completed.
1. Enter your **Braze API Key**. See [Prerequisites](#prerequisites).
1. Enter your **Braze URI**.
1. Click **Next**.
    
    In **EPCC Customer Events**, the **User Track** and **Change Email Subscription Template** checkboxes are selected by default for:
     - **EPCC Customer Created**
     - **EPCC Customer Updated**
     - **EPCC Customer Deleted**
 
    When these checkboxes are selected, any changes in the customer profile information in Commerce causes the webhook event to be created to change the customer profile information in Braze.

    The transformation templates are implemented using the JSONata query language and you must must adhere to the JSONata standards. For example, you can use the following template if you want to concatenate the `external id`, `name`, and `email` using a colon delimiter:

    ```json
    {
	"attributes": [{
		"external_id": id,
        "concatenated_info": $join([external_id,':',name,':',email])
	    }]
    }
    ```
1. Click **Finish**. Your integration is enabled. 

    The three new webhooks created will be displayed on the **SYSTEM** > **Store Settings** > **Webhooks** page.

## Using Braze Integration

You can extend or modify your configuration once you have enabled the integration. The following scenario explains how to change your configuration details in your integration:

1. Log into Commerce Manager. 
1. Go to **CUSTOMERS and ACCOUNTS** > **Customers**.
1. Create a new customer. See [Creating Customers](/docs/commerce-manager/customer-management/cm-customers).
1. Go to **COMPOSER** > **Integrations Hub** > **Executions** to see that the new customer event has been initiated.
1. Extend your customer profile to add more customer-specific information and create new flows and fields. See [creating Flows in Commerce Manger](/docs/commerce-manager/commerce-extension/commerce-extension-in-cm).
    
    For example, create a new field know as `demo_attribute`.

1. Log into Braze and search for the new customer that you have created in Commerce Manager.

    You can see the customer name in the **Custom Attributes** column.

1. Go to **Summary > Reconfigure**.
1. On the **Customer Event Mapping** page, modify your transformation template under **EPCC Customer Updated** section.

    For example, to map `demo_attribute` in Braze, modify the **User Track** transformation template under **EPCC Customer Updated** section:

    ```json
    {
        "attributes":[{
            "external_id": id,
            "email": email,
            "name": name,
            "last_name": last_name,
            "customer_status": status,
            "demo_epcc_attr" : demo_attribute
        ]}
    }
    ```
    
    The transformation templates are implemented using the JSONata query language and you must must adhere to the JSONata standards.

1. Click **Finish** to save your changes.

## Demos

Watch the following video to learn how to integrate Commerce with Braze using the **Integrations Hub** in Commerce Manager:

<iframe width="560" height="315" src="https://www.youtube.com/embed/l9Tg5izBrN4" title="Configuring Braze" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with Google Merchant Center Next

:::caution

This integration uses the new [Merchant API from Google](https://ads-developers.googleblog.com/2024/07/announcing-merchant-api-beta-new.html), which is currently in beta.

:::

You can easily integrate Elastic Path Composable Commerce with your [Google Merchant Center Next](https://www.google.com/retail/) account using the **Integrations Hub** in Commerce Manager. Once you have registered your Elastic Path Composable Commerce-powered storefront with the Google Merchant Center, you can use the integration to upload your products and inventories to your Google Merchant Center account.  This enables your products to be shown in the **Shopping** tab within Google search results, or even within online ads.  When a search result or ad is clicked, it links to your Elastic Path Composable Commerce-powered storefront.

![Google Merchant Center Integration](/assets/composer/google-merchant-center/diagram.jpg)

The integration will synchronize your product data, and optionally, your inventory data between your Elastic Path Composable Commerce store and your Google Merchant Center account.

Whenever a catalog release is published in Elastic Path Composable Commerce, the integration publishes the changes to Google Merchant Center using the [Merchant API](https://developers.google.com/merchant/api).

The following default data is synchronized.  You can optionally configure custom additional attributes to be synchronized.

- Product name
- Product description
- Google Category
- Price
- Sales Price
- Image
- Link to your product on your storefront
- EAN/UPC
- MPN
- Online inventory position

:::caution

- The integration currently does not support bundles.

:::

Whenever a stock transaction is recorded in Elastic Path Composable Commerce, the integration publishes an inventory update to Google Merchant Center using the [Merchant API](https://developers.google.com/merchant/api).  

The integration supports multiple catalogs, multiple languages and multiple currencies.

The integration optionally supports consuming local inventory from a third party system to publish local inventory to Google Merchant Center.  This feature enables the use of Google local ads.

## Prerequisites

Before configuring the integration, there are some prerequisites you need to meet in Google Merchant Center and Elastic Path Composable Commerce.

### Prerequisites in Google Merchant Center Next

You need to perform the following steps in Google Merchant Center Next before configuring the integration.  Details on how to configure each of these elements can be found in [Google's Merchant Center Next online help](https://support.google.com/merchants/answer/12159157/).

1. You must set up a Google Merchant account.
1. In the Google Merchant Center, you must verify ownership of your storefront.
1. For products to be valid in Google, Google requires that you supply shipping details and prices, and a returns policy. The Google Merchant Center does not consider your products valid until this is done.
1. Once your Google Merchant Center Next account is set-up, you need to create an OAuth 2.0 client id to authorize **Integrations Hub** to connect to your Google Merchant Center Next account.  Please consult the [Google Cloud Platform documentation on how to create an OAuth 2.0 Client ID](https://cloud.google.com/application-integration/docs/configure-authentication-profiles#create-oauth). Note that you may need to [create a Project](https://developers.google.com/workspace/guides/create-project#project) and [configure your OAuth consent screen](https://developers.google.com/workspace/guides/configure-oauth-consent) before starting this step.  Please consult the following tables for values that will be needed to configure these steps.

    | OAuth Consent Screen Field Name     | OAuth Consent Screen Field Value       |
    |:------------------------------------|:---------------------------------------|
    | **Authorized Domains**              | `elasticpathintegrations.com` |
    | **Your non-sensitive scopes**       | `openid` |
    | **Your sensitive scopes**           | `Merchant API` |

    | OAuth Client Id Field Name      | OAuth Client Field Value                        |
    |:--------------------------------|:---------------------------------------|
    | **Application Type**            | `Web application` |
    | **Authorized redirect URIs**    | `https://oauth2.us-east-2.elasticpathintegrations.com/callback` for North America implementations or `https://oauth2.eu-west-1.elasticpathintegrations.com/callback` for Europe implementations |

Save the `Client ID` and `Client Secret` that are produced from creation of the `OAuth 2.0 Client ID` as they will be needed in a later step.

### Prerequisites for Commerce

The following steps must be performed in Elastic Path Commerce Manager before configuring the integration.

- Configure supported currencies.
- Configure supported locales.
- Configure product data together with catalogs.
- Configure product pricing (products without prices are not synchronized with Google Merchant Center).
- Generate API key in Commerce Manager.

The integration automatically configures webhooks for catalog and stock transaction events as well as Custom API for catalog/data source mapping and variant mapping entries.
The integration automatically creates a flow and custom field for google category.

## Configuring the Integration

Once you have met the [prequisites](#prerequisites), you are ready to configure the integration in **Integrations Hub**.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Marketing & Communication**, click **Google Merchant Center**. The integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** consist of some details about the integration.
    :::caution
  
    Please refrain from configuring API keys within the `Trigger details` section on this page as this will cause the integration to fail to execute.  All of the APIs will be secured with the value provided in the `Elastic Path Webhook Secret Key` field on the following page of the configuration wizard.

    :::
1. Click **Next**. The **Configuration** page is displayed.
1. Enter the following details in **Commerce Connection**:
    - **Client-ID**  - Your Commerce Client ID.
    - **Client-Secret** - Your Commerce Client Secret.
    - **Token URL** - Your Commerce API Token URL.
    **Token URL** for:
    - EU - `https://useast.api.elasticpath.com/oauth/access_token`
    - US - `https://useast.api.elasticpath.com/oauth/access_token`
1. Click **Connect**. The authorization is successfully completed.
1. Enter the following details in **Google Merchant Center Connection**:
    - **Client-ID**  - Your Google Client ID.
    - **Client-Secret** - Your Google Client Secret.
    - **Token URL** - `https://oauth2.googleapis.com/token`
    - **Authorize URL** - `https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent`
1. Click **Connect**. The authorization is successfully completed.
1. Click **Next**. The **Configuration** page is displayed.
    - **Google Merchant Center ID**  - Your Google Merchant ID.
    - **Merchant API version**  - Version of Merchant API - default v1beta.
    - **Elastic Path Webhook Secret Key**  - The secret API key used to secure outbound Elastic Path webhooks that publish events to this integration.
    - **Product Filtering**  - Select what types of products to send to Google Merchant Center.
        **Product Filtering options**:
        - Parent Products Only - integration sends to Merchant Center standard products and parent products only. It does NOT send child products.
        - Child Products Only - integration sends to Merchant Center standard products and child products only. It does NOT send parent products.
        - Both Parent and Child Products - integration sends to Merchant Center all type of products.
    - **Google Offer Id Strategy** - Specify the Elastic Path product-level field that will be used as the `offer id` for products in Google Merchant Center.

        **Offer Id Strategy options**:
        - `id` - The Elastic Path product id will be used as the offer id within Google Merchant Center.
        - `sku` - The Elastic Path sku will be used as the offer id within Google Merchant Center.
        - `slug`- The Elastic Path slug will be used as the offer id within Google Merchant Center.

        :::caution

        Changing the selection for **Google Offer Id Strategy** after products have already been synchronized to Merchant Center will result in duplicate products in Merchant Center! When choosing a value of sku or slug, please remember that changing these values for a product in your Elastic Path catalog will result in a new, duplicated products in Merchant Center with the new offer id values.

        :::

    - **Product Display Page URL Template**  - A template used to construct URL's to product display pages.

        **Supported url templates**:
        - Simple string url e.g. `https://localhost/p/${id}/${sku}` defines pattern for all product types.
            - Supported placeholders: `${id}`, `${slug}`, `${sku}`
        - Object pattern supports the definition of URL template per product type e.g. `{"standard":"https://localhost/p/${id}/${sku}","parent":"https://localhost/p/${id}/${sku}","child":"https://localhost/p/${parentSku}?variant=${id}"}`.
            - Parent, standard and child elements are required.
            - Supported placeholders: `${id}`, `${slug}`, `${sku}`, `${parentId}`, `${parentSlug}`, `${parentSku}`
    - **Default Availability Status** - Select the default availability status to send when inventory is not managed in Elastic Path.
    - **Inventory Out of Stock Threshold** - The inventory available threshold for determining if a product is in stock or out of stock. Products with inventory positions at or below the specified value will be marked as `out of stock` in Merchant Center.
    - **Default Language** - Select the default language of product content.
    - **Google API Batch Size** - The number of records to consolidate and send to Google APIs in a single API request (batch). **Please leave this as the default value unless you are experiencing performance issues when synchronizing data to Merchant Center.**
    - **Log Level** - The log level used when the integration executes. Used for debugging the integration. **Please leave this as the default value unless you are experiencing issues that require debugging.**
    - **Jsonl processor batch size** - JSONL processor batch size, max allowed 100. Recommended value 100. **Please leave this as the default value unless you are experiencing performance issues when synchronizing data to Merchant Center.**
1. Click **Next**. The **Catalog Mapping** page is displayed.

    - **Send local inventory flag** - Enable this flag to create a separate datasource in Merchant Center for local inventory products and information (inventory in store locations). See [Synchronizing Local Inventory](#synchronizing-local-inventory)

    - **Product Catalog Data Source Mapping** - This configuration contains a mapping of Elastic Path catalogs to Google Merchant Center data sources.  Each mapping includes a selected catalog, language, country and currency. Each mapping entry will create a separate online data source in Google Merchant Center. Catalog, language and currency selection options are based on data configured in Elastic Path.
        - Click on the `+ Add to Product Catalog <> Data Source Mapping` button to add a new row for each Elastic Path catalog and Merchant Center data source you wish to synchronize.

1. Click **Next**. The **Product Exclusions** page is displayed.  This page is used to configure rules that prevent the specified products from being sent to Google Merchant Center.  Products can be excluded by specifying a a product sku, a product slug, a regular expression that matches a product template attribute, or a category. See [Configuring Product Exclusions](#configuring-product-exclusions)

1. Click **Next**. The **Configure Store Code Mapping** page is displayed.  This page is used to configure any store code translations that need to occur when sending local inventory to Merchant Center.See [Synchronizing Local Inventory](#synchronizing-local-inventory)
    - Click on the `Add Value` button to add rows for each needed translation.
    - In each row, place the external store code value in the left field, and the Merchant Center store code value it maps to in the right field.

1. Click **Next**. The **Templates** page is displayed.  This page specifies details on how to transform Elastic Path entities such as products and inventory into Merchant Center format.  These transformations can be used to configure additional fields to pass to Merchant Center when these entities are synchronized.  The transformation is specified as a JSON object that contains a stringified [JSONata](https://jsonata.org/) transform object.
    - **Product Transform Template Definition** - A [JSONata](https://jsonata.org/) transform object that specifies how product data is transformed from Elastic Path to Google Merchant Center format.
    - **Inventory Transform Template Definition** - A [JSONata](https://jsonata.org/) transform object that specifies how product inventory data is transformed from Elastic Path to Google Merchant Center format.

## Using the Integration

To change any configuration details in your integration, open your Integration and go to **Summary** > **Reconfigure**.

In addition, from **Summary**, you can view, pause or delete your integration.

If there is an update to the integration, a message is displayed in **Summary**. Click **Update** to update your integration. You are guided through the steps to update and reconfigure your integration.

### Sending Parent Products, Child Products, or Both

When integrating Elastic Path Composable Commerce with Google Merchant Center Next, merchants can choose how to manage the synchronization of parent products and child products. This is particularly important for product configurations that involve variations (e.g., different sizes or colors), where the parent product represents the main product, and child products represent the different variants.

The integration provides the flexibility to configure which products are sent to Google Merchant Center Next:

- **Parent Products Only**
- **Child Products Only**
- **Both Parent and Child Products**

#### Parent Products Only

When configuring the integration to send **parent products only**, the integration sends standard products and the main product (the parent) without any variants.

#### Child Products Only

By configuring the integration to send **child products only**, the integration sends only standard products and the variant-specific products (child products) to Google Merchant Center Next. Each variation of the parent product (such as different sizes or colors) will be treated as an individual product in the feed.

#### Both Parent and Child Products

When configuring the integration to send **both parent and child products**, the integration will send standard products, the parent product and all of its associated variants (child products). In this scenario, both the main product and its variations will be visible in Google Merchant Center Next.

#### Product Filtering Configuration

In the **Integrations Hub** of Elastic Path Commerce Manager, merchants can configure product filtering to specify which types of products (parent, child, or both) will be sent to Google Merchant Center Next. The available options include:

- **Parent Products Only**: Sends standard products and only the main product listing without variant details.
- **Child Products Only**: Sends standard products and only the individual variants of the product.
- **Both Parent and Child Products**: Sends both the main product and all of its variants along with standard products.

These options allow merchants to control the granularity of product information that is sent to Google Merchant Center Next and customize how their products are presented to customers searching through Google.

#### Important Considerations

- **Google Merchant Center Next Limitations**: When sending child products, ensure that each variant aligns with Google Merchant Center Next’s supported variant attributes (such as size, color, etc.). Misalignment can result in data rejections.
- **Inventory Management**: Inventory updates will need to account for whether you are sending parent, child, or both types of products. Make sure inventory levels are properly tracked for each variant if child products are sent.
- **Changing Product Filtering Configuration** - when changing product filtering configuration in the Google Merchant Center integration in the Integrations Hub, integration DOES not reconcile the data between Elastic Path Composable Commerce and Google Merchant Center. If for example configuration has been changed from "Send Both Parent And Child Products" to "Send Only Parent Products", removal of products previously created in Google Merchant Center needs to be done manually. When using API to send data to Google Merchant Center, merchant may not be able to delete products in Google Merchant Center Next interface, that is why it may be required to remove products using direct API call to Merchant API.

### Sending Google Product Category

When synchronizing product data from Elastic Path Composable Commerce to Google Merchant Center Next, it is crucial to correctly map product categories to Google’s predefined taxonomy. Google Merchant Center uses specific product categories to organize and display products in relevant search results and shopping ads. This category data helps improve product visibility and ensures that listings are compliant with Google’s standards.

#### Google Product Category Mapping

The **Google Product Category** is a field for products submitted to Google Merchant Center. Each product must be assigned to one category from Google’s product taxonomy. These categories are defined by Google and have unique numeric IDs.

For example:

- **Apparel & Accessories > Clothing > Outerwear > Jackets** has the ID **1604**.
- **Electronics > Audio > Headphones** has the ID **1797**.

Merchants must assign products in Elastic Path Composable Commerce to the corresponding Google Product Category ID to ensure that their products are correctly categorized in Google Merchant Center Next.
Custom template field is created automatically by the integration during Integration setup, however products need to be assigned template fields and google categories manually by merchants.

## Localization Considerations

When integrating Elastic Path Composable Commerce with Google Merchant Center Next, merchants who operate in multiple regions must carefully manage localization. Localization ensures that products are presented in the appropriate language, currency, and other region-specific formats for each target market. Proper localization helps improve product relevance and visibility for users in different countries, leading to higher engagement and conversion rates.

The integration supports the following key localization aspects:

- **Multiple Languages**
- **Multiple Currencies**
- **Region-specific Product Information**

### Multi-language Support

For merchants targeting multiple countries with different languages, the integration allows for product information to be synchronized in various languages. Google Merchant Center Next requires that each product be assigned a **content language** that corresponds to the region in which the product will be displayed.

#### How Language Support Works

1. **Language Selection in Google Merchant Center Next**:
   - Google Merchant Center Next supports multiple languages for product content. Each language must be specified as part of the data source configuration.
   - When products are synchronized from Elastic Path Composable Commerce, the language of the product content is mapped to the appropriate language in Google Merchant Center Next.

2. **Localized Product Data**:
   - Merchants must provide localized versions of product attributes such as product name, description for each language. The integration sends this data to Google Merchant Center Next based on the catalog’s locale configuration in Elastic Path Composable Commerce.

When synchronizing product data, the integration will ensure that the correct content is delivered for each region.

:::caution

When a non-default language is specified and a value is not defined in the specified language, the value for the default language is sent to Google Merchant Center.

:::

### Multi-currency Support

For merchants selling products in different currencies, it is essential to configure multi-currency support within Elastic Path Composable Commerce and Google Merchant Center Next. Each product can only have one price per currency, and this must be accurately reflected for each target market.

#### How Currency Support Works

1. **Currency Configuration**:
   - Merchants must configure supported currencies in Elastic Path Composable Commerce. Google Merchant Center only allows one currency per data source, meaning that each data source corresponds to a specific currency for a given region. Integration will automatically create data sources in Google Merchant Center based on configuration in Elastic Path Composable Commerce.

2. **Price Synchronization**:
   - When products are synchronized, the price of the product in the respective currency is sent to Google Merchant Center Next. Merchants must ensure that the correct price is associated with each currency and region combination.

:::caution

When a price for a specified currency is missing for the product, the product information will not be sent to Google Merchant Center. Merchants need to ensure proper pricing information is configured for products in Elastic Path Composable Commerce for products to synchronize properly.

:::

### Region-specific Product Information

In addition to language and currency, other product attributes may vary by region, including:

- **Shipping information** (e.g., shipping times or costs).
- **Tax requirements** (these must be configured manually in Google Merchant Center Next).
- **Regulatory information** (certain regions may have additional compliance requirements for products).

:::caution

The integration does not send tax or shipping information. Please ensure that all region-specific details are properly configured in Google Merchant Center to meet the needs of each target market.

:::

### Managing Multiple Data Sources

For merchants operating in multiple countries or regions, the integration supports the creation of **multiple data sources** in Google Merchant Center Next. Each data source can represent a unique combination of country, language and currency. This ensures that product listings are properly localized for each region.

## Data Mapping

### Catalog to Data Source Mapping Information

The integration between Elastic Path Composable Commerce and Google Merchant Center supports mapping product catalogs to multiple data sources in Merchant Center. Each data source represents a unique combination of country, currency and language. This allows for tailored catalog synchronization based on the localization needs of your store.

#### Mapping Structure

A catalog in Elastic Path Composable Commerce can be mapped to one or more data sources in Google Merchant Center. Each data source is configured based on:

- **Country**
- **Currency**
- **Language**

For each catalog, the integration defines a separate data source for each combination of these attributes.  This ensures that product data is displayed in the appropriate language and currency for each region.

#### Example Data Source Mapping

Consider a business operating in both the United States and Canada. The business has two catalogs - one for the U.S. and one for Canada — each serving multiple languages. The following is an example of how the integration will map catalogs to data sources:

1. **US Catalog**:
   - **Target Country**: United States
   - **Currency**: USD
   - **Languages**: English, Spanish

   Data sources:
   - US English Data Source: `US-en-online`
   - US Spanish Data Source: `US-es-online`

2. **Canada Catalog**:
   - **Target Country**: Canada
   - **Currency**: CAD
   - **Languages**: English, French

   Data sources:
   - Canada English Data Source: `CA-en-online`
   - Canada French Data Source: `CA-fr-online`

#### Local Inventory Data Sources

If local inventory is managed, separate data sources are created to handle this information. For the example above, the following local inventory data sources might be created:

- US Local Inventory (English): `US-en-local`
- US Local Inventory (Spanish): `US-es-local`
- Canada Local Inventory (English): `CA-en-local`
- Canada Local Inventory (French): `CA-fr-local`

#### Primary and Supplemental Data Sources

For each catalog, a **primary data source** is created to handle product data, while a **supplemental data source** is used for online channel inventory updates. The supplemental data source accepts updates to product availability (in stock/out of stock), which is sent separately from the main product data. There will always be one supplemental data source per online channel primary data source created in Google Merchant Center.  If the `Send local inventory flag` is enabled in the configuration, a local channel primary data source will also be created to hold local channel product and local inventory information.

All Merchant Center data sources are created automatically by the integration during configuration and activation.
Information about catalog to data source mapping is stored in an Elastic Path Custom API named `Catalog to GMC Mapping`.
Each entry in this Custom API has the following fields:

- channel
- datasource id - id of the data source object in Merchant Center
- datasource key - feed label of the data source in Merchant Center
- datasource name - name of the data source in Merchant Center
- is primary - flag indicating if data source is a primary datasource or a supplemental data source

Datasources are created based on the information located in Elastic Path Composable Commerce (Custom API entries).

During configuration and reconfiguration, the integration detects if new data sources need to be created based on the catalog to data source mapping configuration in Elastic Path and existing data sources in Google Merchant Center.

- If a new datasource needs to be created (i.e. a new mapping entry has been added to the integration configuration), the integration will create a new data source in Merchant Center and insert a new mapping entry in the `Catalog to GMC Mapping` Custom API.
- If the integration tries to create a new data source with the same label as one already existing in Merchant Center, the integration will create a proper mapping entry in the `Catalog to GMC Mapping` Custom API to the pre-existing Merchant Center data source.
- If mapping has been removed from the integration configuration the entry will be removed from the `Catalog to GMC Mapping` Custom API but **WILL NOT** remove data source from Merchant Center.  This is a fail-safe to avoid inadvertently affecting marketing campaigns that may be using the Merchant Center data source.  The data sources can be manually deleted using the Merchant Center Next console if you are absolutely sure they are no longer needed.

#### Feed Label Structure

Each data source has a unique **feed label** used for synchronizing data. The feed label typically follows this format:

`{catalogId}_{channel}_{language}_{country_code}_{currency_code}`

Feed label examples:

- `e84c3db3_o_en_us_cad` - online channel data source, which handles online inventory and product data
- `e84c3db3_l_en_us_cad` - local channel data source, which handles local inventory and product data

This structure ensures that product and inventory updates are sent to the appropriate data source based on catalog, channel, language and currency.

:::caution

- Only one currency is supported per data source.
- One catalog may be pushed to multiple Merchant Center data sources depending on the configuration of country, currency, channel and language.
- Supplemental data sources handle online inventory updates and do not require a language or label.
- When configuring the integration, you will need to select the Elastic Path catalogs and the desired language and currencies to synchronize. These selections must align with the supported languages and currencies of the target country in Google Merchant Center. - At least one catalog to data source mapping is required to send data to Google Merchant Center.

:::

For more information on setting up data sources in Google Merchant Center, refer to the [Google Merchant Center Data Sources Documentation](https://developers.google.com/merchant/api/guides/data-sources/overview?hl=en).

### Variant Mapping

In the integration between Elastic Path Composable Commerce and Google Merchant Center Next, product variants from Elastic Path Composable Commerce are mapped to the corresponding attributes in Google Merchant Center. This mapping allows the flexibility to define and synchronize variations of a product, such as different sizes, colors, or materials, ensuring that all variations are accurately represented on Google Merchant Center.

Google Merchant Center Next supports a limited set of attributes for product variations, which include:

- **Size**
- **Color**
- **Pattern**
- **Material**
- **Age Group**
- **Gender**

Each of these variant attributes needs to be mapped correctly between Elastic Path Composable Commerce and Google Merchant Center Next to ensure proper synchronization.

#### Variant Mapping Behavior

Variant mapping in the integration allows merchants to define how Elastic Path Composable Commerce variant types and options correspond to Google Merchant Center Next variant attributes. These mappings ensure that when a product with variants is sent to Google Merchant Center Next, the correct attributes are assigned and displayed for each variant. If the variant mapping is not defined, the product will be sent as a regular, non-variant product.

##### Variant Mapping Structure

Each variant mapping consists of the following fields:

1. **Elastic Path Composable Commerce Variant Name**: This is the name of the variant as defined in Elastic Path Composable Commerce (e.g., "Size", "Color").
2. **Elastic Path Composable Commerce Variant Option Name**: The specific option for that variant (e.g., "Medium" for Size, "Red" for Color).
3. **Google Merchant Center Next Variant Attribute Name**: The corresponding attribute name used by Google Merchant Center Next (e.g., "Size", "Color").
4. **Google Merchant Center Next Variant Attribute Value**: The specific value for that attribute in Google Merchant Center Next (e.g., "M" for Medium, "Red" for Color).

##### Example Mapping

For example, consider the following scenario with a product that has size and gender variants:

| Elastic Path Composable Commerce Variant Name | Elastic Path Composable Commerce Variant Option | Google Merchant Center Next Variant Attribute Name | Google Merchant Center Next Variant Attribute Value |
|------------------------------------------|--------------------------------------------|--------------------------------------------------|----------------------------------------------------|
| Size                                     | Medium                                     | Size                                             | M                                                  |
| Size                                     | Large                                      | Size                                             | L                                                  |
| Gender                                   | Male                                       | Gender                                           | Male                                               |
| Gender                                   | Female                                     | Gender                                           | Female                                             |

In this case, when the product is sent from Elastic Path Composable Commerce to Google Merchant Center Next, the correct size and gender variants will be reflected in the product listing.

##### Handling Unmapped Variants

If a product in Elastic Path Composable Commerce has a variant that does not have a corresponding mapping in Google Merchant Center Next, that product will be sent as a regular product without any variant information. It is the responsibility of the merchant to ensure that all variant mappings are correctly defined and aligned with the attributes supported by Google Merchant Center Next.

Additionally, if a variant in Elastic Path Composable Commerce does not have a corresponding option in the mapping (i.e., the variant exists but the option is missing), the integration will send the incoming value for that variant type.

#### Preconfigured Standard Variant Mappings

The integration comes with preconfigured standard mappings for the following common variants:

| Elastic Path Composable Commerce Variant Name | Elastic Path Composable Commerce Variant Option | Google Merchant Center Next Variant Attribute Name | Google Merchant Center Next Variant Attribute Value |
|------------------------------------------|--------------------------------------------|--------------------------------------------------|----------------------------------------------------|
| Age Group                                | Newborn                                    | Age Group                                        | newborn                                             |
| Age Group                                | Infant                                     | Age Group                                        | infant                                              |
| Age Group                                | Toddler                                    | Age Group                                        | toddler                                             |
| Age Group                                | Kids                                       | Age Group                                        | kids                                                |
| Age Group                                | Adult                                      | Age Group                                        | adult                                               |
| Color                                    | Red                                        | Color                                            | Red                                                 |
| Color                                    | Blue                                       | Color                                            | Blue                                                |
| Gender                                   | Male                                       | Gender                                           | Male                                                |
| Gender                                   | Female                                     | Gender                                           | Female                                              |
| Gender                                   | Unisex                                     | Gender                                           | Unisex                                              |
| Material                                 | Cotton                                     | Material                                         | Cotton                                              |
| Pattern                                  | Striped                                    | Pattern                                          | Striped                                             |
| Size                                     | Small                                      | Size                                             | S                                                   |
| Size                                     | Medium                                     | Size                                             | M                                                   |
| Size                                     | Large                                      | Size                                             | L                                                   |

These standard mappings can be extended or modified based on the specific requirements of the merchant. New variants can be defined, and custom mappings can be added to handle unique product configurations.

#### Customizing Variant Mappings

Merchants can customize the variant mapping by adding or modifying the mappings through the integration configuration. This allows for flexibility in aligning product variants in Elastic Path Composable Commerce with the supported attributes in Google Merchant Center Next.

To customize the variant mappings, merchants must access the Custom API (Variant Mapping) and provide the following information:

- The name of the variant in Elastic Path Composable Commerce.
- The name of the corresponding Google Merchant Center Next variant attribute.
- Any specific mapping logic for the variant options.

By defining these mappings, merchants ensure that their product listings in Google Merchant Center Next accurately reflect the full range of product variants available in Elastic Path Composable Commerce.

:::caution

- Only variant attributes officially supported by Merchant Center can be used. Merchants must ensure that all mappings align with the variant attributes allowed by Google.
- The integration only sends explicitly mapped variants to Google Merchant Center Next. Any unmapped variants will result in the product being treated as a non-variant product.
- It is the responsibility of the merchant to maintain and update variant mappings to ensure accuracy across all product listings.

:::

For more details on variant support in Google Merchant Center Next, refer to the [Google Merchant Center Documentation](https://support.google.com/merchants/answer/6324507).

## API Rate Limits and Quotas

When integrating Elastic Path Composable Commerce with Google Merchant Center Next, it is essential for merchants to manage the API rate limits imposed by Google Merchant Center Next. The integration itself does not have a built-in mechanism to control or monitor API rate limits. Therefore, **it is the merchant’s responsibility to ensure that the necessary rate limits are available** for the integration to function correctly.

Google Merchant Center Next enforces limits on the number of API calls that can be made per day and per minute, and exceeding these limits can result in errors, failed data synchronization, or temporary access restrictions.

### API Rate Limits in Google Merchant Center

Google Merchant Center Next has API rate limits that define how many requests can be made within a certain period. These limits are typically set by Google based on the type of API (e.g., product insert, inventory updates, etc.) and the number of records being processed. Merchants need to understand these limits and ensure that they are not exceeded.

Examples of rate limits imposed by Google Merchant Center Next:

- **Daily Quota**: The total number of API requests allowed per day.
- **Per-Minute Quota**: The number of API requests allowed per minute.

These limits are subject to change based on Google’s policies, so merchants should regularly review their API usage and check Google Merchant Center's quota limits for their account.

API quotas, rate limits and usage can be viewed in the [Google Cloud Console APIs & Services](https://console.cloud.google.com/apis/dashboard).  Make sure to view the quotas and rate limits for the `Merchant API` service.

You can also fetch your API quota usage via the [Merchant Center Quotas REST API](https://developers.google.com/merchant/api/reference/rest/quota_v1beta/accounts.quotas/list?hl=en).

More details on Google Cloud API Quotas can be found in the [Google Cloud Documentation](https://cloud.google.com/docs/quotas/view-manage).

### Merchant Responsibilities

As the integration does not monitor or enforce API rate limits, **merchants must take responsibility** for ensuring that their Google Merchant Center Next API usage stays within allowable limits. Merchants are responsible for:

1. **Monitoring API Usage**:
   - Merchants should regularly monitor their API usage to ensure they do not exceed their rate limits.
   - Google Merchant Center Next provides APIs to check your quota usage, allowing you to track the number of requests being made and how close you are to your limit.
   - Merchants can configure quota usage alerts to receive notifications of quota status by following the instructions in the [Google Cloud Documentation](https://cloud.google.com/docs/quotas/set-up-quota-alerts).

2. **Adjusting Synchronization Frequency**:
   - If the merchant’s API limits are frequently being exceeded, they may need to adjust the frequency of catalog publishing within Elastic Path, inventory synchronization, or other operations that trigger API requests.

3. **Requesting Higher Quotas**:
   - For businesses with large catalogs or frequent inventory updates, it may be necessary to [request higher API quotas from Google](https://cloud.google.com/docs/quotas/view-manage#requesting_higher_quota) to avoid rate limit issues.

Failure to stay within API rate limits may result in:

- **Temporary throttling**: Google may temporarily reject API requests until the quota resets.
- **Data synchronization failures**: Products or inventory updates may fail to be sent, resulting in incomplete or out-of-date information in Google Merchant Center Next.
- **Service disruption**: Exceeding quotas frequently may result in service degradation or limitations imposed by Google.

### Batch Requests in the Integration

To optimize API usage and reduce the number of individual requests made to Google Merchant Center Next, the integration supports **batching** of API requests wherever possible. This means that multiple updates (e.g., product data or inventory updates) are consolidated into a single API request, reducing the overall number of API calls. This doesn't have impact on quota, since even when using batch calls to Google Merchant Center each request entity withing the batch is considered as separate API call.

The integration natively supports throttling when making calls to Elastic Path Composable Commerce and uses batching where possible when calling Elastic Path APIs.

## Customization Options

The integration between Elastic Path Composable Commerce and Google Merchant Center Next offers several customization options that allow merchants to tailor the integration to their specific business needs. These options provide flexibility in how data is synchronized, how products are presented, and how product attributes are mapped to Google Merchant Center Next. By leveraging these customization settings, merchants can ensure that their product listings reflect their unique business requirements.

### Key Customization Options

1. **Product Filtering Options**

    This option allows merchants to control how products with variants (e.g., sizes, colors) are synchronized to Google Merchant Center Next.

    The available options include:
     - **Parent Products Only**: Sends only the main (parent) product without variations.
     - **Child Products Only**: Sends only the variant-specific (child) products.
     - **Both Parent and Child Products**: Sends both the parent product and its associated variants.

    This setting is available within the integration configuration wizard of the Google Merchant Center integration, under the `Product Filtering` configuration field.

2. **Variant Mapping**

    This mapping allows merchants to present different product variation attributes and options correctly in Google Merchant Center Next.
    Merchants can map product variants from Elastic Path Composable Commerce to Google Merchant Center Next’s supported variant attributes, such as size, color, material, pattern, gender, and age group.
    Custom mappings can be created to ensure that specific product variants align with Google’s predefined variant attributes.

   Example:
   - Elastic Path Composable Commerce Variant: **Size**
   - Google Merchant Center Next Attribute: **Size**
   - Variant Value: **Medium (M)**

    This mapping can be configured with the `Custom APIs` section of Commerce Manager once you have initially configured the Google Merchant Center integration.

3. **Custom Product Attributes**
    This mapping allows merchants to tailor which product-level attributes from Elastic Path are synchronized with their Google Merchant Center account to meet their specific business or promotional needs.
    Merchants can map pre-existing Elastic Path product attributes or define new attributes (e.g., promotional labels, custom tags) and map them to the corresponding Google Merchant Center Next fields.  This mapping is exposed as a configurable JSONata transformation template.  The transformation customization also supports basic formatting adjustments if necessary.

   Example:
   - Custom Attribute: **Promotional Label**
   - Mapped to: **Google’s custom attribute field**

    This setting is available within the integration configuration wizard of the Google Merchant Center integration, under the `Product Transform Template Definition` configuration field.  The integration also supports a similar customizable transformation for online inventory data fields within the `Inventory Transform Template Definition` field.

    Examples of the default product and inventory JSONata transform values are listed below, for reference.

    **Standard inventory JSONata transformation:**

    ```json

    { "expression": "{\"channel\": channel, \"contentLanguage\": contentLanguage, \"feedLabel\": feedLabel, \"attributes\": { \"availability\": availability }, \"offerId\": currentStockPosition.id }"}

    ```

    **Standard product JSONata transformation:**

    ```json

    {
      "expression": "{
        'method': 'POST',
        'url': '/products/' & parameters.merchantId & '/productInputs',
        'body': {
          'channel': parameters.channel,
          'contentLanguage': parameters.language,
          'feedLabel': parameters.feedLabel,
          'offerId': id,
          'attributes': {
            'title': attributes.name,
            'price': {
              'amountMicros': attributes.price.amount * 10000,
              'currencyCode': parameters.currency
            },
            'description': attributes.description,
            'googleProductCategory': attributes.extensions.google_product_category,
            'mpn': attributes.manufacturer_part_num,
            'gtin': [attributes.upc_ean]
          }
        }
      }"
    }
    ```

    **Customizing product transformation template**

    The transformation operation is passed a copy of the Elastic Path product JSON object as input to the transformation, as well as the transformation template.  An example of a transformation expression along with an example request and example response can be found in [Jsonata Playground](https://try.jsonata.org/7C6VZHyJp). Any values that should be passed to Merchant Center must be output by the transformation within the `body` property of the output JSON object.

    **Example of a Product Transformation Customization**

    The following example demonstrates how to customize the product transformation so that the Elastic Path product `commodity_type` attribute is stored in a custom Merchant Center attribute and also in the Merchant Center `productType` field.

    Consider the following snippet of an Elastic Path product JSON object.

    ```json
        {
            "attributes": {
                "price": {
                    "CAD": {
                        "amount": 10000,
                        "includes_tax": false,
                        "tiers": null
                    }
                },
                "commodity_type": "physical",
                "base_product": false,
                "upc_ean": "123456",
                "manufacturer_part_num": "12345",
                "extensions": {
                    "products(gmc)": {
                        "google_product_category": "1"
                    }
                }
            }
        }
    ```

    This will require modification of the `body` section of the transformation with an additional `customAttributes` property and also to include the `productTypes` property under the `attributes` property. Please refer to this example of a [modified transformation](https://try.jsonata.org/lCvqDsGxV) to see the necessary transformation.

    :::caution

    It is recommended to test the transformation in the Jsonata Playground to ensure it is working as expected. After the change, the transformation needs to be stringified and set in the `expression` value of the `Product Transform Template Definition` configuration value.  There are several online tools to stringify JSON objects, such as [jsonformatter.org](https://jsonformatter.org/json-stringify-online).

    :::

    Please refer to the [Merchant API productInputs documentation](https://developers.google.com/merchant/api/reference/rest/products_v1beta/accounts.productInputs/insert) for details about attributes that are required or supported natively by Merchant Center as well as where to store any custom attributes.

## Configuring Product Exclusions

:::note

An alternative method to exclude products from being sent to Google Merchant Center can be achieved by configuring a catalog and hierarchy in Product Experience Manager that contains relationships to ONLY the products to be sent to Google Merchant Center.  Then select this catalog in the Catalog Mapping configuration page.

:::

Merchants who want to prevent certain products in mapped catalogs from being sent to Google Merchant Center can use the Product Exclusions configuration page to exclude them from the data source.  Products can be excluded using any combination of four options:

- **SKU** - Click on the **Add to SKUs** button and enter the sku.  Products with the entered SKU will be excluded from all data sources.
- **Product Slug** - Click on the **Add to Slugs** button and enter the slug.  Products with the entered slug will excluded from all data sources.
- **Product Attributes** - Click on the **Add to Attributes** button and select the desired product attribute. The drop down is prepopulated with all template attributes in the store. Enter the value in the attribute value field.  Products with a matching value for the selected attribute will be excluded from the feed.  The value field is a regular expression.  Please consult the [documentation for JavaScript regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions) if you need help. The following section also contains some examples of common regular expressions.
- **Categories** - Click on the **Add to Categories** button and select the desired category.  The drop down is pre-populated with all categories from all mapped catalogs. All products in the selected categories will be excluded from all data sources.

### Product Exclusions by Product Attribute - Examples

The following examples provide commonly used regular expressions when excluding products by attribute.

To exactly match an attribute value, `foo`, the following regular expression can be used.

```regex
^foo$
```

To match any attribute value that contains the string `foo`, the following regular expression can be used.

```regex
foo
```

To match any attribute value that starts with the string `foo`, the following regular expression can be used.

```regex
^foo.*
```

To match any attribute value that ends with the string `foo`, the following regular expression can be used.

```regex
.*foo$
```

## Synchronizing Local Inventory

Merchants who desire to utilize Google Local Inventory Ads, the integration supports synchronization of local inventory via an API.  This local inventory may come from your point of sale or ERP system. The API accepts a URL to a remotely hosted file, containing local inventory records in JSON Lines format.  The file is read by the integration, transformed into Merchant Center format and synchronized to your Merchant Center account.

### Local Inventory Pre-Requisites

The merchant must configure all physical store locations within their Google Merchant Center account prior to loading local inventory.  Physical store locations are configured within a Merchant Center account by linking a Business Profile for each store. Full details on this process can be found in [Google Merchant Center Help](https://support.google.com/merchants/answer/12160023).

The Local Inventory Add-on also must be configured in the Merchant Center account.  A full list of the steps required to implement local inventory ads and free local listings should be reviewed in the [Google Merchant Center Help](https://support.google.com/merchants/answer/14615117).

:::caution

It can take Merchant Center up to 48 hours to fully link a Business Profile (i.e. a physical store location) to a Merchant Center account.  Even if the store shows as linked in the Merchant Center account, it may not yet be fully linked within Google's backend systems. If you attempt to load local inventory and are seeing errors about invalid store codes and you are certain that your store codes are correct, you may need to wait several hours for the Google systems to properly finish linking your Business Profiles to your Merchant Center account. You can use the [Replay](#troubleshooting) feature to easily resubmit any failed executions.

:::

### Steps to Synchronize Local Inventory

1. Create a local inventory file in the proper format.
    - The file must be in JSON Lines format.
    - A [JSON Schema file](/assets/composer/google-merchant-center/external-local-inventory-record-schema.json) is available to assist with understanding how to properly construct each record in the JSON lines file.  The schema can also be used by JSON schema tooling to validate your records are properly formatted.
    - The API supports the file being gzipped for performance reasons, but it is not required.
    - An example snippet of a properly formatted JSON lines local inventory file is below.

    ```json
    {"sku":"sku123abc","storeCode":"store123","price":10.99,"salePrice":8.99,"currency":"USD","salePriceStartDate":"2024-07-01T00:00:00-06:00","salePriceEndDate":"2024-09-01T23:59:59-06:00","quantity":0,"instoreLocation":"Aisle X | Bin Y"}
    {"sku":"sku123abc","storeCode":"store456","price":10.99,"salePrice":7.99,"currency":"USD","salePriceStartDate":"2024-07-01T00:00:00-06:00","salePriceEndDate":"2024-09-01T23:59:59-06:00","quantity":10,"instoreLocation":"Aisle X | Bin Y"}
    {"sku":"sku456xyz","storeCode":"store123","price":59.99,"currency":"USD","quantity":10}
    ```

1. Host the file in an accessible location.  This could be within an AWS S3 bucket, Google Drive, etc.
1. Configure store code mapping, if necessary, to map the store codes sent in the JSON Lines file to the store codes configured in your Merchant Center account if they do not match.  See the Store Code Mapping section of [Configuring the Integration](#configuring-the-integration).
1. Call the API and pass it the URL to your local inventory file.  An [Open API specification is available](/assets/composer/google-merchant-center/external-local-inventory-ingress-request-openapi.yml) to understand the proper way to call the API.  The unique URL to the API (e.g. the `{local-inventory-flow-id}`) for your integration instance can be found within the Integration Summary section of the Google Merchant Center integration within Integrations Hub.
    - Below is an example request payload to the local inventory API.

    ```json
        {
            "inventoryFileUrls": [
                "https://{path}/inventory_yyyy_mm_dd.jsonl.gz"
            ]
        }
    ```

1. Repeat this process as needed to keep local inventory synchronized, bearing in mind your Merchant Center [API quotas and rate limits](#api-rate-limits-and-quotas).

:::caution

The Google Merchant Center API for local inventory enforces case-sensitivity on store codes.  Please keep this in mind when configuring your store code mapping.

:::

## Troubleshooting

You can debug issues in the **Executions** viewer within Integrations Hub.

1. Navigate to the **Integrations Hub** section within **Commerce Manager** for your Elastic Path store.
1. Open the **Google Merchant Center** integration.
1. Click on the **Executions** tab.
1. Browse through the list of executions on the left side to find the target execution you wish to debug.
    - Use the **Filter** if necessary to help find the specific execution to debug.
1. Select the target execution from the list and view the outputs and log entries of the execution in the lower right panel to help troubleshoot any issues.
1. If the execution failed due to a retryable error, the execution can be re-run by clicking on the **Replay** icon of the execution instance in the list on the left side.
    - Retriable errors include:
        - Network transmission / socket errors.
        - Missing or incorrect configurations with your Google Merchant Center account that have been corrected.
        - Google Merchant Center changes that were not successfully applied by Google at the time of execution.

:::caution

All Google Merchant Center changes are asynchronous and can take anywhere from a few minutes to up to 48 hours to fully reflect in your Merchant Center account. This statement is true for changes made in the Google Merchant Center Next console, as well as changes made via the integration. This can occasionally cause errors during flow execution.  See the previous section for instructions on how to **Replay** failed flow executions for a quick way to address these types of issues.

:::

---

## Integrating with Google Content API for Shopping

You can integrate Commerce with the Google Content API for Shopping using the **Integrations Hub** in Commerce Manager. Once you have registered your Elastic Path Commerce Cloud-powered storefront with the Google Merchant Center, you can use the integration to upload your products so that they automatically appear in Google Search results in the **Shopping** tab. When a search result is clicked, it links to your Commerce-powered storefront.

![Google Content API for Shopping](/assets/google-shopping.png)

Whenever a catalog release is published in Commerce, the integration invokes the Google Content API for Shopping. The following data is displayed:

- Product name.
- Product description.
- Price.
- Image.
- Link to your product on your storefront.
- EAN/UPC.

The integration supports adding new products, updating existing products, and deleting products. 

:::caution

- All products default to an **in_stock** status in Google, regardless of their availability in Commerce.
- The integration does not support bundles.

:::

## Prerequisites

Before configuring the integration, there are some prerequisites you need to meet in Google Merchant Center and Commerce.

### Prerequisites in Google Merchant Center

You need to perform the following steps in Google Merchant Center before configuring the integration.

1. You must set up a Google Merchant account.
1. In the Google Merchant Center, you must verify ownership of your storefront. 
1. For products to be valid in Google, Google requires that you supply shipping details and prices, and a returns policy. The Google Merchant Center does not consider your products valid until this is done.
1. Once your Google Merchant account is set-up, you need to create an API authentication key for the Content API. The API key is some JSON data which you must save securely and not check-in to source control. You need the `client_email` and `private_key` from this JSON file when you configure the integration. 

    | Option | Description                            |
    |:------------------------------------|:---------------------------------------|
    | **client_email**                    | The email address associated with your Google Merchant account. |
    | **private_key**                     | Your Google Merchant account private key. |
    | **google_merchant_id**              | Your Google Merchant account ID. |

For more information, see [Merchant Center - Google for Retail](https://www.google.com/retail/solutions/merchant-center/).

### Prerequisites for Commerce

You need to perform the following steps in Commerce before configuring the integration.

1. Products that you want to synchronize with the Google Content API for Shopping must have a `EAN/UPC` attribute configured. Although this is an optional attribute for products in Commerce, Google analyses your product data for quality and may downrank your products in search results if your products do not have the `EAN/UPC` attribute configured.
1. You must have created your catalogs. See [create a catalog](/docs/api/pxm/catalog/create-catalog).
1. You must have collected the setup information from Commerce. You can find this information in Commerce Manager under **SYSTEM**, in **Application Keys**, when logged in as a user with Seller Admin privileges.

    | Option | Description                            |
    |:------------------------------------|:---------------------------------------|
    | **API Base URL**                    | Your Commerce API Base URL. For example, `https://useast.api.elasticpath.com/oauth/access_token`. See [Regions and URLs](/guides/Getting-Started/elastic-path-domains#regions-and-urls). |
    | **Client ID**                       | Your Commerce Client ID. |
    | **Client Secret**                   | Your Commerce Client Secret. |

    :::note
    When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
    :::

## Configuring the Integration

Once you have met the [prequisites](#prerequisites), you are ready to configure the integration in **Integrations Hub**.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Marketing & Communication**, click **Google Content API for Shopping**. The integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** consist of some details about the integration.
1. Click **Next**. The **Configuration** page is displayed.
1. Complete the information on the **Configuration** page.

    1. Complete the Google Merchant Account configuration fields.
        - **client_email**  - The email address associated with your Google Merchant account.
        - **private_key** - Your Google Merchant account private key.
        - **google_merchant_id** - Your Google Merchant account ID.
        - **target_country_and_currency** - The target country and currency that your products are sold in. The integration is currently limited to a single target country per store. 
        - **target_language** - The ISO language code for your products. 
    1. Complete the Commerce Configuration Data fields.
        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.
        - **Token URL** - Your Commerce API Token URL.
    1. Click **Connect** to make sure that the authentication is completed successfully.
    1. In **epcc_base_url**, type your Commerce API base URL. For example, `https://useast.api.elasticpath.com`. See [Regions and URLs](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
    1. Create a new secret or passphrase and type it in **webhook_key**. This is used to authenticate the Elastic Path webhook and the integration.
    1. Complete the Integration Tuning Values fields. 
    
        :::note
        We recommend that you do not change the defaults. Contact Customer Success for more information.
        :::

        - **batch_size** - The number of pages to group into a single batch. Default is **250**.
        - **concurrent_threads** - Each batch is processed by a thread. Default is **10**. 

    1. Complete the Storefront Configuration Values fields.
        - **product_page_url_host_path_prefix** - the first part of the URL to the product page on your storefront. Google uses this to link the search result to your storefront. 
        - **product_identifier_scheme** - The attribute that is used to identify products in the URL of your product page. Select from:
            - Slug
            - SKU
            - Product ID
        - **url_parameter_string** - An optional parameter added to the end of the URL for the product page.
1. Click **Finish**. Your integration is enabled. You need to configure an integration for each store whose products you want to appear in Google searches.
1. Once the Integration is configured and running, any product data that is published to the catalog is automatically synchronized to Google. You can review the data in the Google Merchant Center. 

    :::caution
    Depending on the number of products in your catalog, it may take several minutes for your product data to appear in the Google Merchant Center, once the Commerce catalog is published.
    :::
    
1. You should review your products in the Google Merchant Center to make sure they are appearing in Google searches. You can check the status of your products in your Merchant Console.

## Using the Integration

To change any configuration details in your integration, open your Integration and go to **Summary** > **Reconfigure**.

In addition, from **Summary**, you can view, pause or delete your integration.

If there is an update to the integration, a message is displayed in **Summary**. Click **Update** to update your integration. You are guided through the steps to configure your integration.

## Troubleshooting the Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

From **Step Outputs**, you can select a step to see its output. You can retry an individual step.

## Demo

<iframe width="560" height="315" src="https://www.youtube.com/embed/NVF5P1tnxCM" title="Configuring Google Merchant Center" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with Postmark

You can quickly and easily integrate Commerce with Postmark using the **Integrations Hub** in **Commerce Manager**. Integration with Postmark enables you to send emails to single or multiple recipients.

The integration with Postmark supports custom events published by external event sources, in addition to the native Commerce event types. The Postmark event handler is implemented as part of the integration process; it accepts the Commerce event types and other custom events configured in external sources. For more information on custom events, see [Publishing Custom Events in External Sources](#publishing-custom-events-in-external-sources).

To be accepted by the event handler, the events must be in the specified JSON format. For more information on the JSON formatting, see [Configuring Event-Mapping Configurations](#configuring-event-mapping-configurations).

## Postmark Email Template

In Postmark, you can configure email templates that define the emails you want to send to your recipients. Each email template has an `Alias` name and `ID` that is used for identifying which template is used for sending emails to recipients. You can also specify a name and subject ID for each template. 

The dynamic fields in a template, for example, first name and order ID, are mentioned within curly braces (`{}`) using the mustache format.

Attachments that you include in an email template are sent as documents attached with an email. You can also embed attachments in the email body.

![Postmark Email Template](/assets/postmark-email-template.png)

## How the Postmark Integration Works

This is how the Postman integration works:

1. Configure email templates in Postmark.

2. An Commerce developer configures the integration in Composable Commerce > **Integrations Hub**.

    A new instance is created and the `Init Flow` is executed. The `Init Flow` validates whether the events received are correctly formatted.

3. The integration creates or updates the webhooks configured in Commerce.

    :::note
    For custom events, webhooks are not created in the Commerce because the events are published in external sources.
    :::

4. A secret key is also generated when you configure webhooks in Commerce. This secret_key is required for sending the events to Postmark.
5. When an event is triggered in the Commerce, the `Main Flow` is executed. 

    The `Main Flow` is an asynchronous trigger that utilizes a set of event-mapping configurations. These configurations analyze the data received in Commerce Manager through events and generate appropriate values for a Postmark email template. The analysis is required to populate the dynamic values for the fields contained in the Postmark email template, for example, the first name of the email recipient and the order ID.

6. Once the mapping is done and information for the Postmark email template is generated, the Postmark API sends the email to the recipients.

## Configuring Event-Mapping Configurations

Mapping of information between Commerce Manager and Postmark is done through a combination of event names and JSON values. This combination of mapping key + values is referred to as event-mapping configurations. The configurations specify a set of parameters for an event, including both native Commerce events and custom events configured in external source. The primary information mapping is done with the event name.

When you are configuring the Postmark integration in Commerce Manager, you can specify these event-mapping configurations.  

![Postmark Integration in Commerce Manager](/assets/postmark-integration-commerce-manager.png)

- **Key**: This is the event name that triggers the webhook events, for example, `order.paid`, `order.created`. For more information on the complete list of Commerce events, see [Observable Events](/docs/api/integrations/integrations-introduction#observable-events). For custom events, the names must contain the `custom.` prefix, for example, `custom.contact.us`. To know more about custom events, see [Publishing Custom Events in External Sources](#publishing-custom-events-in-external-sources).
- **Value**: The values are JSON objects. They can either be a single JSON object or an array of JSON objects. Here is an example:

```json 
{
  "messagingProvider": {
    "templateId": "d-7fd1f0f905974f9abc9f8f44f883e0b5",
    "from": "customer-service@foo.com",
    "to": "$.payload.data.customer.email",
  },
  "dynamicFieldMapping": {
    "marketingImage": "http://example.com/static/value.png",
    "firstName": "$.payload.data.billing_address.first_name",
    "lastName": "$.payload.data.billing_address.last_name",
    "orderid": "$.payload.data.id",
    "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
    "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
  },
  "metadata": {
    "fieldx": "fieldl value"
  },
  "attachments": []
}
```

    The following example illustrates a sample event-mapping configuration that includes an array of JSON objects; this triggers two emails for a single event:

```json
[
  {
    "messagingProvider": {
      "templateId": "d-5377hisuhf477h2hhbahd563gag5h",
      "from": "no-reply@foo.com",
      "to": "customer-service@foo.com",
    },
    "dynamicFieldMapping": {
      "marketingImage": "http://example.com/static/order-notification.png",
      "firstName": "$.payload.data.billing_address.first_name",
      "lastName": "$.payload.data.billing_address.last_name",
      "orderid": "$.payload.data.id",
      "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
      "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
    },
    "metadata": {
      fieldx: "fieldl value"
    },
    "attachments": []
  },
  {
    "messagingProvider": {
      "templateId": "d-7fd1f0f905974f9abc9f8f44f883e0b5",
      "from": "customer-service@foo.com",
      "to": "$.payload.data.customer.email",
    },
    "dynamicFieldMapping": {
      "marketingImage": "http://example.com/static/thank-you.png",
      "firstName": "$.payload.data.billing_address.first_name",
      "lastName": "$.payload.data.billing_address.last_name",
      "orderid": "$.payload.data.id",
      "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
      "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
    },
    "metadata": {
      metafield1: "fieldl value"
    },
    "attachments": []
  }
]
```
The **Value** field of **Event-Mapping** can contain the following sections and attributes:

- `messagingProvider`: The `messagingprovider` section contains the following attributes:

    - `templateId`: Unique identification number of the email template you have created in Postmark. You can also provide the `alias` name of the template.  
    - `from`: Email address of the sender used in the `from` field in an email template.  
    - `to`: Email address of the recipient used in the `to` field in an email template.  
    - `allowMultipleRecipients`: If the value is set to `true`, an array of recipients are included in the `to` field in an email template. If set to `false`, only a single recipient is included in the `to field.  
    - `replyto`: This is an optional attribute.  
    - 'headers`: An optional attribute to include any custom header you would like to add to the emails you send.  
    - `trackOpens`: An optional attribute that activates tracking of an email.
    - `tracklinks`: An optional attribute that activates link tracking for any link included in the email body.  
    - `messageStream`: An optional attribute that specifies an ID used for sending the email messages. If no value is provided, the email message is set to default outbound transactional stream.

:::note
 [JSONata](http://docs.jsonata.org/overview.html) is the query language used for these attributes. JSONata provides JSON Path style queries and adds support for more advanced queries and even transformations. 
:::

- `dynamicFieldMapping`: This section contains a combination of keys and values required to generate dynamic information for the email template, for example, order ID.
- `metadata`: This section contains a combination of keys and values required to generate metadata (additional) information for the email template. The information included in the `metadata` section is stored against the transaction, so that the information can be later viewed from the sent logs. You can assign any name to this section.
- `attachments`: Each attachment section must contain the following attributes. The attributes are mapped to generate attachment details included in a Postmark email template. You can provide multiple attachments in an email.

    - `name`: Name of the attached document.
    - `content`: The content must be a base64 encoding of the attached document.
    - `contentID`: This value is required if you have embedded the content ID of the attached document in the Postmark email template you have configured.
    - `contentType`: This is the kind of content included in the attached document, before being base64 encoded, for example, image in JPEG format. Here is an example:

    ```json
    {
    "triggered_by": "custom.contact-us",
    "configuration": {
    "secret_key": "ABC123ZY715XdZkAMrrsN410xSd99yir0WAECl7dij+M="
    },
    "payload": {
      "data": {
       "customer_email": "john.doe@example.com",
       "subject": "Question about Product ABC",
       "body": "Does it come in XS size?",
       recieved_at": "2022-09-09T12:34:38.679Z",
       "attachments": [{
        name: "attachmentName",
        content: "SGV5LCBpdCBqdXN0IGEgdGVzdCBzdHJpbmc=",
        contentID: "cid:1",
        contentType: "image/jpeg",
        }]
       }
      }
     }```

## Generating Dynamic Information for Email Templates

The event-mapping configurations are analyzed to retrieve information for an email template. Here are few examples:
 
 - Single field mapping: The `To` field in an email template denotes the email address of the recipients. The email address is obtained from the `payload.data.customer.email` value of an event-mapping configuration:

    ```
    "to": "$.payload.data.customer.email",
    ```

- Array value mapping: The 'items' field in an email template denotes either a table or a list of items, for example, contents of an order in an order notification. The values for the 'item' field are obtained from the `messagingprovider` section that generates an array of JSON objects:

    ```
    "items": "$.payload.included.items.{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
    ```

- Static value mapping: The following example illustrates a static mapping where no analysis is performed because the value does not start with `$`. The information included in the event-mapping value is used in the email template without any mapping:

    ```
    "marketingImage": "http://example.com/static/value.png",
    ```

## Prerequisites

You must complete the following before integrating the Commerce with Postmark:

1. Here is an example of the Commerce event illustrating the JSON format followed as a minimum requirement:

```json
{
  "id":"63d5b706-ee05-418c-a2bf-b34be26da9d4",
  "triggered_by":"order.created",
  "attempt":1,
  "configuration":{
  "url":"https://demo/demo",
  "secret_key":"deadbeefdeadbeef"
  },
  "integration":{
  "id":"204fe27e-17aa-4e26-b2a2-54d1ebe0bcd6",
  "integration_type":"webhook",
  "name":"Event Logger",
  "description":"Captures and stores all published events"
  }
  "payload": {
    "data": "{ ... }"
  }
  ...etc...
}
```

   :::note
   The `triggered_by` field is mandatory to identify the event and it is used while mapping the event with a set of event configurations. An appropriate value for the `secret_key` field is also required, else the event is rejected; the key is the SHA256 hash of the `client_secret` used in the integration connection parameters.
   :::

2. Here is an example of an event published by other external sources illustrating the JSON format followed as a minimum requirement:

```json
{
  "triggered_by":"custom.delivery-failed",
  "configuration":{
      "secret_key":"deadbeefdeadbeef"
  },
  "payload": {
    "data": { ... }
  }
}
```

:::note
The value in the `triggered_by` field must contain the `custom.` prefix, which is important for the correct operation of the `Init Flow`. The `Init Flow` is executed when you initiate the Postmark integration in the **Integrations Hub** of Commerce Manager.
:::

3. You require the following information for integrating Postmark in the **Integrations Hub** of Commerce Manager:

    - **EPCC-Connection**: The Commerce connection details.
    - **Postmark-API-Key**: The `Postmark API Key` generated in your Postmark account.

## Configuring Postmark Integration

Once you have completed the [Prerequisites](#prequisites), you are ready to configure the Postmark integration:

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Under **Marketing & Communication**, click **Postmark Email**.
3. Click **Configure**.

    A window appears where you must configure the integration details.

4. In the **Initial Configuration**, click **Next**.
5. In the **Configuration** section, perform the following:

    i. Enter the **Postmark-API-Key**.

        For more information, see [Prerequisites](#prerequisites).

    ii. In the **Event-Mapping** section, click [Add Log Level Multiple Values](/assets/add-value-postmark.png).
    
        - In the **Key** field, enter the event name for which you want to trigger the webhook.
        - In the **Value** field, enter appropriate sections and attributes.

   :::note
   For more information on **Key** and **Value** fields, see [Configuring Event-Mapping Configurations](#configuring-event-mapping-configurations).
   :::

    iii. Optional step: in the **Log Level**, you can enter appropriate values for which you want to configure log entries. To add multiple values, click ![Add Log Level Multiple Values](/assets/add-value-postmark.png).  

    :::note
    You can configure additional details for monitoring. For example, enable **Error on Fail**, if you want to be notified when there is a a failure in sending emails to recipients through Postmark. 
    :::
    iv. In the **EPCC Postmark Collection**, click **Connect**.

        Your connection details are successfully authorized.

7. Click **Finish**.

## Verifying Postmark Integration

Perform the following to verify whether the Postmark integration is successful or not:

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Under **Marketing & Communication**, click **Postmark Email**.
3. Under **Trigger Details**, click the arrow next to **Main Flow**.
4. Copy the URL.
5. Go to Postman.
6. Paste the URL that you have copied from Commerce Manager.
7. Select the `POST` method.
8. In the **Body**, enter the event details in JSON format:

    - You must mention the event name in the **triggered_by** attribute.
    - You must mention the **secret_key** under **configuration**.
    
    :::note
    To generate the secret_key, log in to Commerce Manager > **SYSTEM** > **Store Settings** > **Webhooks**. Click the webhook event that you have configured while integrating with Postmark. Copy the **Secret Key**.
    :::

9. Send the request. The API response is successful and the recipient receives the intended email.

## Publishing Custom Events in External Sources

You can create custom events in sources external to Commerce. The custom events must conform to the following guidelines:

- Must include a top level `triggered_by` attribute. 
- Must include a top level `configuration` attribute with `secret_key` included.

    :::caution
    The `secret_key` value is similar to the EPCC-Client-Secret key, but hashed with SHA256 and base64 encoded.  You can obtain this value from a pre-existing webhook event configured in Commerce Manager > **SYSTEM** > **Store Settings** > **Webhooks**. The specific webhook event must be related to Postmark integration.
    
    If you don't have any events configured, then use the client secret ID used in your Commerce connection for your Postmark integration, sha256 hash it, and then base64 encode it. 
    :::

- Must include HTTP POST to trigger the webhooks for an integration.  The webhook URL is visible either in the Integration configuration panel or in Commerce Manager > **SYSTEM** > **Store Settings** > **Webhooks**.
- Include any data under `payload.data` as illustrated in the following example:

```json
{
  "triggered_by": "custom.contact-us",
  "configuration": {
    "secret_key": "ABC123ZY715XdZkAMrrsN410xSd99yir0WAECl7dij+M="
  },
  "payload": {
    "data": {
      "customer_email": "john.doe@example.com",
      "subject": "Question about Product ABC",
      "body": "Does it come in XS size?",
      "recieved_at": "2022-09-09T12:34:38.679Z",
    }
  }
}
```

## LoopbackFlow

You can use the `LoopbackFlow`**` to test the event-mapping configurations, without involving Postman. This flow operates similarly to `Main Flow`, without sending the event-mapping keys and values to Postmark.

You must send both the event name and the values containing the sections and their attributes:

```json
{
 "event": {... },
 "config": [{"key": "order.created", "value": ""}]
}
```

The values must be sent in string format – first verify whether the JSON values are correctly formatted and then convert them to a string, using [JSON String Converter](https://jsonformatter.org/json-stringify-online).

The following example illustrates a response you will receive in LoopBackFlow:

```json
[
   {
       "ErrorCode": 0,
       "Message": "loopback OK",
       "SubmittedAt": "null",
       "MessageID": "0 from batch of 2 ",
       "Template": {
           "To": "joe.bloggs@elasticpath.com",
           "From": "joe.bloggs@elasticpath.com",
           "TemplateId": 30725951,
           "TemplateModel": {
               "image1": "https://localhost/product-a.jpg",
               "firstName": "Ron",
               "orderid": "45936d34-7ce7-48fd-9673-eae9b434dd5e"
           },
           "Metadata": {
               "metaField1": "value for metaField1"
           }
       },
       "EventConfiguration": {
           "messagingProviderHydrated": {
               "from": "joe.bloggs@elasticpath.com",
               "templateId": 30725951,
               "to": [
                   "joe.bloggs@elasticpath.com",
                   "joe.bloggs@elasticpath.com"
               ],
               "allowMultipleRecipients": true
           },
           "dynamicFieldMappingHydrated": {
               "image1": "https://localhost/product-a.jpg",
               "firstName": "Ron",
               "orderid": "45936d34-7ce7-48fd-9673-eae9b434dd5e"
           },
           "metadataHydrated": {
               "metaField1": "value for metaField1"
           }
       }
   },
   {
       "ErrorCode": 0,
       "Message": "loopback OK",
       "SubmittedAt": "null",
       "MessageID": "1 from batch of 2 ",
       "Template": {
           "To": "joe.bloggs@elasticpath.com",
           "From": "joe.bloggs@elasticpath.com",
           "TemplateId": 30725951,
           "TemplateModel": {
               "image1": "https://localhost/product-a.jpg",
               "firstName": "Ron",
               "orderid": "45936d34-7ce7-48fd-9673-eae9b434dd5e"
           },
           "Metadata": {
               "metaField1": "value for metaField1"
           }
       },
       "EventConfiguration": {
           "messagingProviderHydrated": {
               "from": "joe.bloggs@elasticpath.com",
               "templateId": 30725951,
               "to": [
                   "joe.bloggs@elasticpath.com",
                   "joe.bloggs@elasticpath.com"
               ],
               "allowMultipleRecipients": true
           },
           "dynamicFieldMappingHydrated": {
               "image1": "https://localhost/product-a.jpg",
               "firstName": "Ron",
               "orderid": "45936d34-7ce7-48fd-9673-eae9b434dd5e"
           },
           "metadataHydrated": {
               "metaField1": "value for metaField1"
           }
       }
   }
]
```

## Mapper Flow

You can use the `Mapper Flow` when you want to verify whether an event included in the Postmark integration is generating correct information for a Postmark email template.

The following example illustrates a sample response that you will receive in `Mapper flow`:

```json
[
   {
       "messagingProviderHydrated": {
           "from": "joe.bloggs@elasticpath.com",
           "templateId": 30725951,
           "to": [
               "joe.bloggs@elasticpath.com",
               "joe.bloggs@elasticpath.com"
           ],
           "allowMultipleRecipients": true
       },
       "dynamicFieldMappingHydrated": {
           "image1": "https://localhost/product-a.jpg",
           "firstName": "Ron",
           "orderid": "45936d34-7ce7-48fd-9673-eae9b434dd5e"
       },
       "metaDataHydrated": {
           "metaField1": "value for metaField1"
       }
   }
]
```

## Demos

Watch the following video to learn how to integrate Commerce with Postmark using the **Integrations Hub** in Commerce Manager:

<iframe width="560" height="315" src="https://www.youtube.com/embed/8s2H7B8rwYg" title="Integrating with Postmark" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with SendGrid

You can quickly and easily integrate Commerce with SendGrid using the **Integrations Hub** in Commerce Manager. Integrating with SendGrid allows you to send emails to your customers when events in Commerce are triggered. For example, you can send a customer registration email when you create a customer in Commerce, or send an order confirmation email when an order is created.

An example of how an email is sent using a SendGrid integration is described below.

1. When an order is created, an `order.created` event is triggered.
1. Once an `order.created` event is received by the webhook, the integration begins to execute.
1. The integration:
    - Uses **Init Flow** to validate that your Commerce events are in the correct format and creates a Commerce webhook for each event.
    - Uses **Main Flow** to:
        - Consume the events.
        - Passes a SendGrid email **Template ID** so that SendGrid knows which email template to use.
        - Populates the fields configured in a SendGrid dynamic template with the values from Commerce.
        - Uses [SendGrid V3 Mail Send API](https://docs.sendgrid.com/api-reference/mail-send/mail-send) to send an email to your customer.

## Prerequisites

You must have completed the following tasks in SendGrid before configuring the integration in Commerce.

1. Created an account.
1. Verified your sender email addresses. This can be a single sender or inbox providers that you own in your domain.
1. Obtained a SendGrid API key with, at least, **Mail Send** access.

See [SendGrid Documentation](https://docs.sendgrid.com/) for more information.

## Best Practices

Below is an overview of the steps you need to follow to integrate Commerce with SendGrid.

1. Make sure you have met the prerequisites. See [Prerequisites](#prerequisites).
1. Collect the setup information for SendGrid and Commerce.  See [Collecting Your Setup Information](#collecting-your-setup-information).
1. Create a dynamic template in SendGrid. See [Creating Dynamic Templates in SendGrid](#creating-dynamic-templates-in-sendgrid).
1. Create the event mapping between Commerce and the SendGrid email template. See [Configuring Event Mapping](#configuring-event-mapping).
1. Create a SendGrid integration in **Commerce Manager** > **Integrations Hub**.  See [Configuring the SendGrid Integration](#configuring-the-sendgrid-integration).

:::note
When integrating with third party providers, we recommend you use the closest region in the third party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Collecting Your Setup Information

Before you begin configuring your SendGrid integration in Commerce Manager, you need to collect the necessary setup information from SendGrid and Commerce Manager.

:::caution
Collect the following information and make sure you have it available, for example, in a text file, before configuring your SendGrid integration in Commerce Manager. If you leave the **SendGrid Email** page in **Integrations Hub**, the integration is not saved and you must remove the integration and create a new one.
:::

### Collecting SendGrid Setup Information

You need the **SendGrid API Key ID** which is the API Key for your SendGrid account. In SendGrid, API keys are found in **Settings** > **API Keys**.

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Creating Dynamic Templates in SendGrid

Once you have created a dynamic template in SendGrid, you need to do the following. For more information, see [SendGrid Documentation](https://docs.sendgrid.com/).

1. Add placeholders in your dynamic template for the data that you want to pass from Commerce to the email.
1. Make a note of the **Template ID** as you need this when configuring your SendGrid integration in  **Commerce Manager** > **Integrations Hub**.

## Configuring Event Mapping

Each event mapping configuration is a set of parameters for a specific event type in Commerce. The event mapping configuration is stored as key + value pairs.

- An event key is the name of the Commerce event that triggers the event mapping configuration. For example, `order.paid` or `order.created`. See [Observable events](/docs/api/integrations/integrations-introduction#observable-events) for a list of Commerce events.
- An event value is a JSON object that must contain a `messagingProvider` element and a `dynamicFieldMapping` element. The event value object can be:
    - A single object (if you want to send one email when a Commerce event is triggered).
    - An array of event value objects (if you want to send more than one email from SendGrid when a Commerce event is triggered).

### Configuring a `messagingProvider` object

The attributes and types for the `messagingProvider` object are defined in the following table.

| Attribute             | Type                                      | Required | Description                                                                                                                                                                                                                                       |
|:----------------------|:------------------------------------------|:---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `templateId`          | string                                    | Required | The `templateId` of your SendGrid Dynamic Email template. See [Creating Dynamic Templates in SendGrid](/docs/composer/integration-hub/marketing-communication/sendgrid#creating-dynamic-templates-in-send-grid).                                  |
| `from`                | string                                    | Required | The email address to use in the `From` email field. This is the email address you verified in SendGrid. See [Prerequisites](#prerequisites).                                                                                                        |
| `name`                | string                                    | Optional | A free text name that allows you to replace your sender email address with a custom name, so the recipient sees the specified text instead of the actual email address. For example, **MyCompany Customer Service** or **No Reply at MyCompany**. |
| `replyTo`             | object or array                           | Optional | An object with two properties, `email` and `name`.  Replies to emails sent via this SendGrid configuration will be sent to the specified email. An array of multiple objects can also be provided if multiple reply-to addresses are desired.
| `dynamicFieldMapping` | [object](#the-dynamic-field-mapping-object) | Required | The key + value pairs that maps data from Commerce to the SendGrid dynamic template.                                                                                                                                                              |

#### The `dynamicFieldMapping` object

The `dynamicFieldMapping` object uses [JSONata](http://docs.jsonata.org/overview.html) as its query language.

The attributes and types for the `dynamicFieldMapping` object are defined in the following table.

| Attribute | Type | Description |
| --- | --- | --- |
| *SendgridTemplateFieldnames* | string | The placeholder fields from your SendGrid dynamic templates. See [Creating Dynamic Templates in SendGrid](/docs/composer/integration-hub/marketing-communication/sendgrid#creating-dynamic-templates-in-send-grid). |
| *ElasticPathCommerceCloudPayload* | string | The payload delivered to your webhook from Commerce contains the information about the resources affected by the fired event. See [Integration Payload](/docs/api/integrations/integrations-introduction). The payload must include:  A `to` field that defines the email address that the email should be sent to. This can be defined as a single email address or a comma-separated list of email addresses.An optional `replyTo` object that defines a mandatory `email` and optional `name` that replies should be sent to. This can be defined as a single object or an array. If the `replyTo` is also set within the `messagingProvider` section, then all objects are combined in a single array before sending to SendGrid. See example below.The data from Commerce that you want to include in a SendGrid email. The format of the data depends on whether you have a single item or an array of items. A single item is in the format `$payload.data.EPCCresource`. For example, `$payload.data.billing.address.first_name`. An array of items is in the format of `$payload.data.EPCCobjectname.{'EPPCresourcename': EPCCresourcevalue,'EPPCresourcename': EPCCresourcevalue}`. For example, `$.payload.included.items.{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}`. |

Below is an example of a single `messagingProvider` object.

```json
{
  "messagingProvider": {
    "templateId": "d-7fd1f0f905974f9abc9f8f44f883e0b5",
    "from": "no-reply@foo.com",
    "name": "Foo Customer Service",
    "replyTo": {
      "name": "Foo Customer Service",
      "email": "customer-service@foo.com"
    }
  },
  "dynamicFieldMapping": {
    "marketingImage": "http://example.com/static/value.png",
    "to": "$.payload.data.customer.email",
    "replyTo": [
      {
        "email": "$.payload.data.warehouseEmail",
        "name": "My Fulfillment Services"
      },
      {
        "email": "$.payload.data.customerServiceAuditEmail"
      }
    ],
    "firstName": "$.payload.data.billing_address.first_name",
    "lastName": "$.payload.data.billing_address.last_name",
    "orderId": "$.payload.data.id",
    "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
    "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
  }
}
```

Below is an example of an array of `messagingProvider` objects.

```json
[
  {
    "messagingProvider": {
      "templateId": "d-5377hisuhf477h2hhbahd563gag5h",
      "from": "no-reply@foo.com",
      "name": "No Reply at Foo.com"
    },
    "dynamicFieldMapping": {
      "marketingImage": "http://example.com/static/order-notification.png",
      "to": "customer-service@foo.com, jane.doe@example.com",
      "firstName": "$.payload.data.billing_address.first_name",
      "lastName": "$.payload.data.billing_address.last_name",
      "orderId": "$.payload.data.id",
      "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
      "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
    }
  },
  {
    "messagingProvider": {
      "templateId": "d-7fd1f0f905974f9abc9f8f44f883e0b5",
      "from": "customer-service@foo.com"
    },
    "dynamicFieldMapping": {
      "marketingImage": "http://example.com/static/thank-you.png",
      "to": "$.payload.data.customer.email",
      "firstName": "$.payload.data.billing_address.first_name",
      "lastName": "$.payload.data.billing_address.last_name",
      "orderId": "$.payload.data.id",
      "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
      "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
    }
  }
]
```

### Publishing custom events from external systems

You can trigger an email to be sent from SendGrid using a custom event from a system that is external to Commerce. For example, you might have a **Contact Us** page where your customers can ask questions and you can email them in return. Custom events use HTTP POST to post to the webhook endpoint for the integration.  The URL of the webhook endpoint is visible in either the **SendGrid Email** integration in **Integrations Hub** or within **SYSTEM** > **Store Settings** > **Webhooks**. You can configure your storefront to post an event to this webhook and trigger a custom event so that the integration causes a SendGrid email to be sent.

The fields that you define in your custom event object can be anything you want. For example, you may want to include `subject`, `body` and `received_at` fields, in addition to any Commerce data that needs to be sent to your SendGrid email template.

The attributes and types for custom event object are defined in the following table.

| Attribute          | Type     | Description                                  |
|:-------------------|:---------|:---------------------------------------------|
| `triggered_by`     | string   | The target key from the event mapping configuration. See [Configuring Event Mapping](#configuring-event-mapping). |
| `configuration`    | object   | Contains `secret_key` which is the Commerce Secret. See [Collecting Your Setup Information](#collecting-your-setup-information). |
| `customfieldnames` | [object] | You can use custom fields to specify any additional values that you want to populate in the email template. Custom fields can be of any type and are queried using the `dynamicFieldMapping` element in the event mapping configuration. |

Below is an example a custom event object.

```json
{
  "triggered_by": "custom.contact-us",
  "customer_email": "john.doe@example.com",
  "subject": "Question about Product ABC",
  "body": "Does it come in XS size?",
  "received_at": "2022-09-09T12:34:38.679Z",
  "configuration": {
    "secret_key": "ABC123ZY715XdZkAMrrsN410xSd99yir0WAECl7dij+M="
  }
}
```

## Configuring the SendGrid Integration

Once you have:

- [Met the prerequisites](#prerequisites).
- [Collected your setup information](#collecting-your-setup-information).
- [Created your dynamic templates in SendGrid](/docs/composer/integration-hub/marketing-communication/sendgrid#creating-dynamic-templates-in-send-grid).
- [Configured your event mapping](#configuring-event-mapping).

You are ready to configure the SendGrid integration in **Integrations Hub**.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Email and SMS Integrations**, click **SendGrid Email**. The **SendGrid Email** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** consist of the webhooks for the **Init Flow** and **Main Flow**. You do not need to change any of the information here.

    :::caution
    Do not configure any API keys for the webhooks. The webhooks are authorized using the `configuration.secret_key` value in the request body.  Configuring an API key directly on the webhook results in a non-functional integration.
    :::
1. Click **Next**. The **Configuration** page is displayed.
1. Complete the information in the **Configuration** page and configure the following.

    - **EPCC-Base-URL** - Your Commerce API Base URL.
    - **EPCC-Client-ID**  - Your Commerce Client ID.
    - **EPCC-Client-Secret** - Your Commerce Client Secret.
    - **SendGrid-API-key** - The **SendGrid API Key ID** which is the API Key for your SendGrid account.
1. In **Event-Mapping**, click **+ Add value**.
1. In **Key** type the name of the Commerce event that, when triggered, causes an email to be sent from SendGrid. For example, `order.created` or `customer.created`.
1. In **Value**, copy the `messagingProvider` object that you want to use when the Commerce event is triggered.

![Sendgrid event mapping](/assets/sendgrideventmapping.PNG)

1. Click **+ Add value** to add as many key + value pairs as you want.
1. Click **Finish**. Your integration is enabled.

## Using SendGrid Integration

To add more event mappings to your SendGrid integration, go to **Summary** > **Reconfigure**.

In addition, from **Summary**, you can view, pause or delete your SendGrid integration.

If there is an update to the Commerce SendGrid Email integration, a message is displayed in **Summary**. Click **Update** to update your integration. You are walked through the steps to configure your integration.

You can test your Commerce payloads in **Test**.

## Troubleshooting the SendGrid Email Integration

You can debug any issues in **Executions**. Each time an event that triggers an email to be sent from SendGrid is executed, you can click on that execution. The **Logs** shows the output and any errors or warnings.

From **Step Outputs**, you can do the following.

1. Select **Validate Event Mappings** to see which events were properly formatted. Events that are not properly formatted are ignored and are, therefore, not shown.
1. Select **EPCC Event Publish Trigger** to see the code that was posted that triggered the email. This is useful if you want to check the code.
1. Select **Apply Event Mapping to Request** to see all the values that were sent to SendGrid.
1. Select **Send Email via SendGrid** to see the HTTP code and status text for the API response that sent the email to SendGrid.

Select **Retry** to initiate an execution again.

---

## Integrating with Fluent Commerce

You can quickly and easily integrate Commerce with Fluent Commerce using the **Integrations** hub in **Commerce Manager**. Integration with Fluent Commerce enables you to manage your orders for your business. Fluent Commerce also handles product inventory because it provides you a complete view of your stock, which can be published in all channels, including store front.

## How the Fluent Commerce Integration Works

This is how integration with Fluent Commerce works:

- Products are synced from Composable Commerce to Fluent Commerce.
- Customers are synced from Composable Commerce to Fluent Commerce.
- Orders are sent from Composable Commerce to Fluent Commerce – you can configure webhook events for the following Commerce event types:

    - `order.created`
    - `order.updated`
    - `order.fulfilled`
    - `order.paid`
    - `order.authorized`

    When you are integrating with Composable Commerce, you can setup webhook events for multiple scenarios, for example, you have triggered a webhook for the `order.paid` event – orders from Composable Commerce are sent to Fluent Commerce when the payment is processed.

- Orders are captured in Composable Commerce – after a payment for an order is authorized in Composable Commerce, the order details are sent to Fluent Commerce and the order items are allocated. You can trigger webhook event to capture the order in Composable Commerce.
- Orders can be marked as `paid` in Composable Commerce – you can trigger a webhook event to mark an order as paid when it is shipped to a customer. For more information, see [Mark Orders as Paid in Commerce Manager](/docs/composer/integration-hub/order-marketplace-inventory/fluent#mark-orders-as-paid-in-commerce-manager).

## Integrating Composable Commerce with Fluent Commerce

### Prerequisites

You must complete the following before configuring the integration with Fluent Commerce.

#### Composable Commerce connection details

You can get the following API credentials in Commerce Manager from **SYSTEM** > **Application Keys**:

- **Token URL**: The API token URL:

   - EU: `https://euwest.api.elasticpath.com/oauth/access_token`
   - US: `https://useast.api.elasticpath.com/oauth/access_token`
    
:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. For more information, see [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::
    
- **Client ID**: Your Commerce Client ID.
- **Client Secret**: Your Commerce Client Secret.

:::note
You must log in to Commerce Manager as a user with seller admin privileges.
:::

#### Fluent Commerce connection details

You must get the following details from Fluent support:

- **Fluent Host**: The Fluent Commerce API host URL.
- **Retailer Username**: Username to access the Fluent Commerce account as a retailer.
- **Retailer Password**: Password to access Fluent Commerce account as a retailer.  
- **OAuth 2.0 Client Id**: Client ID to connect with Fluent Commerce APIs.  
- **OAuth 2.0 Client Secret**: Client secret to connect with Fluent Commerce APIs.  
-  **Retailer ID**: The retailer ID of Fluent Commerce where you would like to sync your orders, customers, and products.    
- **Product Catalog Reference**: The product catalog reference of Composable Commerce where you would like to sync all your products.  

### Configuring Fluent Commerce integration 

Once you have completed the [Prerequisites](/docs/composer/integration-hub/order-marketplace-inventory/fluent#prerequisites), you are ready to configure the Fluent Commerce integration:

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Under **Order Management**, click **Fluent Commerce**.
3. Click **Configure**. A window appears where you must configure the integration details.
4. In the **Initial Configuration**, click **Next**.
5. In the **Connection Details**:  

    1. In the **Commerce Connection** section, enter the following appropriate values:
    
        - **Client ID**
        - **Client Secret**
        - **Token URL**
    
          For more information, see [Composable Commerce connection details](#commerce-cloud-connection-details).
    
    1. Click **Connect**. The authorization is successfully completed.
    
    1. In the **Fluent Commerce Connection** section, enter the following appropriate values: 
    
        - **Fluent Host**
        - **Retailer Username**
        - **Retailer Password**
        - **OAUth 2.0 Client ID**
        - **OAuth 2.0 Client Secret**

        For more information, see [Fluent Commerce connection details](#fluent-commerce-connection-details).

6. Click **Next**.
7. In the **GraphQL Mutation** section, click any box to modify the default values of the following based on your business requirement:

    - **Create Customer Mutation**
    - **Update Customer Nutation**
    - **Create Order Mutation**
    - **Create Order and Customer Mutation**
    - **Create Standard Product Mutation**
    - **Update Standard Product Mutation**
    - **Create Variant Product Mutation**
    - **Update Variant Product Mutation**

8. Click **Next**.
9. In the **Templates** section, click any box to modify the template values based on your business requirement:

    - **Order Template**: A default template is provided to create or update orders in Fluent Commerce.  
    - **Customer Template**: A default template is provided to create or update customers in Fluent Commerce.  
    - **Standard Product Template**: A default template is provided to create or update products in Fluent Commerce.  
    - **Variant Product Template**: A default template is provided to create or update variant products in Fluent Commerce.   

    :::note
    GraphQL uses these templates as variables.
    :::

10. Click **Next**.
11. In the **Configuration** section, enter the following appropriate values:

    - **Fluent Retailer ID**
    - **Product Catalog Reference**

      For more information, see [Fluent Commerce connection details](#fluent-commerce-connection-details).

    - **Enable Customer Webhook**: Enable this if you want to configure a webhook event in Composable Commerce to be triggered when a customer is created or updated.
    - **Enable Product Webhook**: Enable this if you want to configure a webhook event in Composable Commerce to be triggered when products are created or updated while publishing a catalog.
    - **Enable Order Webhook**: Enable this if you want to configure a webhook event in Composable Commerce to be triggered when orders are created or updated.
    - **Order Events**: Click **+ Add Value** to add multiple order events for which you want to configure webhook events. By default, `order.paid` is selected. You can select any of the following values:

        - `order.created`
        - `order.updated`
        - `order.fulfilled`
        - `order.paid`
        - `order.authorized`

    :::note
    To check the webhook events that you have configured in Commerce Manager, under **SYSTEM**, click **Store Settings**, and then **Webhooks**.
    :::

12. Click **Finish**.

## Verifying Composable Commerce and Fluent Commerce Integration

There are multiple ways to verify the success of this integration. Here are two examples provided:

### Option 1

1. In Commerce Manager, publish a product catalog. For more information, see [Publishing Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/catalog-configuration#publishing-catalogs).
1. On the **Products** page, click any product to view the SKU.
1. Copy the product SKU.
1. Go to Fluent Commerce.
1. Click **Product Catalogues** under **Inventory & Product**.
1. Click **VARIANT PRODUCTS**.
1. In the search bar, click **Ref:**, and then enter the product SKU that you have copied in Commerce Manager. The product details are displayed in Fluent Commerce.

### Option 2

In the storefront, register yourself as a new customer. 

If your integration is successful, you can view the new customer account details both in Composable Commerce and Fluent Commerce:

 - In Commerce Manager, under **Customers and Accounts**, click **Customers**.
 - In Fluent Commerce, under **Order Management**, click **Customer**.

## Mark Orders as `Paid` in Commerce Manager

When a customer places an order in the storefront and completes the payment, the order status in Fluent Commerce is updated to `COMPLETE`. However, the order payment status in Commerce Manager still appears as `Authorized`. To mark this order as `Paid` in Commerce Manager, perform the following steps:

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Click **Fluent Commerce**.
3. Under **Trigger Details**, click **Capture Order (Elastic Path)**.
4. Copy the webhook URL.
5. Go to Fluent Commerce.
6. Under **Orchestration**, click **Orchestration**.
7. In the list, click **ORDER**. This displays the rule-based workflows based on which the order status that is modified in Commerce Manager.
8. Click **HOME DELIVERY**. The **Workflow Editor** appears.
9. In the **ORDER** section, click ![Order Complete Status](/assets/order-complete-status.png) that appears before **COMPLETE**. The **OrderComplete** window appears.
10. In the **Rules** section, replace the webhook URL with the one you have copied from Commerce Manager.
    
    When an order payment is complete, a webhook event is now triggered in Commerce Manager, and the order payment status is updated to `Paid`.

## Demos

- Watch the following video to learn how to integrate Commerce with Fluent Commerce using the **Integrations Hub** in Commerce Manager:

    <iframe width="560" height="315" src="https://www.youtube.com/embed/UFifBu3CxbM" title="Integrating with Fluent Commerce" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

- Watch the following video to verify the Fluent Commerce integration with Commerce:

    <iframe width="560" height="315" src="https://www.youtube.com/embed/OR4XjL43MMM" title="Verifying Fluent Commerce Integration" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with Onport

You can quickly and easily integrate Commerce with Onport using the **Integrations Hub** in Commerce Manager. Onport supports marketplace and/or dropship vendor models. Integrating Onport with Commerce means you can enable support for marketplace and dropship vendor models in Commerce. The **Onport Integration** supports the following features.

- **Product** changes in Onport causes webhook events to be generated to change product data in Commerce.
- **Inventory** changes in Onport causes webhook events to be generated that increment or decrement inventory in Commerce.
- **Price** changes in Onport causes webhook events to be generated to change price information in Commerce.
- **Order** changes in Commerce, like creating and updating, trigger webhook events that subsequently cause orders to be created and updated in Onport. The following Commerce event types can be used to generate webhook events.

    - `order.created`
    - `order.updated`
    - `order.fulfilled`
    - `order.paid`
    - `order.authorized`

- **Fulfilment** vendor fulfil order item changes in Onport trigger webhook events that are subsequently updated in Commerce. This includes tracking information.
- **Cancellation** if a vendor is unable to fulfill an item then they can cancel the item. This triggers a webhook in Onport. Based on the webhook, Commerce updates its data to reflect cancellation of the item.
- **Split Orders** orders generated in Commerce causes webhook events to be generated in Onport that allow Onport to split an order based on vendors. 

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/zi4ewTPiGjU" title="Integrating with Onport" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Synchronizing Onport Product Data With Commerce Product Data

As part of the Onport Integration, changes in product data in Onport automatically updates product data in Commerce. This is achieved using the Onport Integration Product Template. A Webhook in Onport is configured as part of this integration, so no manual intervention is required.

1. In Commerce, create your [templates](/docs/commerce-manager/product-experience-manager/extending-products/templates). Any Onport product attributes should have corresponding attributes in your Commerce templates.
1. When configuring the Onport Integration in **Integrations Hub**, from **Template** page, click **Edit** underneath **Product Template**.
1. Update the **Product Template** to map the Commerce product attributes to the Onport product attributes. For example, suppose you want to save Onport variant id, vendor id and vendor name in Commerce, along with the product clothing material, if that exists.

    The example below shows how this should look in the **Product Template**.

    ```json
    "attributes":[[
    {
    "templateSlug":"products(extensions)",
    "templateAttributes": [
      [
        {
          "fieldSlug":"ep_brand",
          "type":"string",
          "value":customFieldVariants.custom_field[name='brand'].value
        },
        {
          "fieldSlug":"ep_material",
          "type":"string",
          "value":customFieldVariants.custom_field[name='material'].value
        },
        {
          "fieldSlug":"onport_variant_id",
          "type":"string",
          "value": $string(variant.id)
        }
      ]  ~> $filter(function($v, $i, $a) {
        $v.value
      })
    ]
    }
    ]] ~> $filter(function($v, $i, $a) {
    $count($v.templateAttributes) > 0
    })
    ```

### Pre and Post Processors - Product
There is pre and post processor configuration for products. This is where you can configure external endpoints to do any pre or post processing. For example, if you have an external system which can manipulate images or update descriptions using Generative AI then add the endpoint as part post processor.

## Synchronizing Onport Price Data With Commerce

If **Enable Price Webhook** is enabled then a webhook is setup in Onport by the integration and all the price details are stored in Commerce. Prices are loaded as per the selected pricebook during the configuration. A default template is provided with the integration. You must not change `priceBookName` in the template. You must change the currency and also define whether this amount includes tax.

## Synchronizing Onport Inventory Data With Commerce

If **Enable Inventory Webhook** is enabled then a webhook is setup in Onport by the integration and all the inventory details are stored in Commerce.

## Synchronizing Commerce Order Data With Onport Order Data

As part of the Onport Integration, changes in orders in Commerce automatically updates order data in Onport. Suppose you are adding shipping charges to an order and the shipping SKU is STANDARD-DELIVERY. You must change the Order Template so that this is available in Onport. A webhook in Commerce is configured as part of the integration, so no manual intervention is required.

1. You must exclude the shipping sku from the line item so that it does not appear as part of the product in Onport.
1. When configuring the Onport Integration in **Integrations Hub**, from **Template** page, click **Edit** underneath **Product Template**. The example below shows how this should look in the **Product Template**.

    ```json
    "lineItems": [
    payload.included.items[sku!='STANDARD-DELIVERY' and meta.display_price.with_tax.unit.amount >= 0].{
    "externalId": $$.payload.data.id & "_" & id,
    "name": name,
    "quantity": quantity,
    "price": meta.display_price.with_tax.unit.amount / 100,
    "taxable": false,
    "variant": {
        "sku": sku,
        "externalId": sku
    }
    }
    ]
    ```

    :::note
    You must not change the `lineItems.*.externalId` value. This is because it is in the format of the Elastic Path Order ID concatenated with the Elastic Path Order Item ID separated with a hyphen. This value is required during the fulfillment and cancellation process.
    ::: 

1. From **Template** page, click **Edit** underneath **Order Template**. The example below shows how this should look in the **Order Template**.

    ```json
    "options": {
    "findOrCreateChannelVariant": true
    },
    "shipping": [
    payload.included.items[sku='STANDARD-DELIVERY' and meta.display_price.with_tax.unit.amount >= 0].{
    "code": "shipping-fee",
    "name": "Shipping Fee",
    "serviceLevel": "shipping-service-level",
    "price": meta.display_price.with_tax.unit.amount / 100
    }
    ]
    ```

### Pre and Post Processors - Orders
There are pre and post processor configuration for orders. This is where you can configure external endpoints to do any pre or post processing. For example, if you have an external system which can send email then add the endpoint as part post processor.

## Synchronizing Onport Fulfillment Data With Commerce

Vendors in Onport are able to initiate fulfillment/shipping process. For example, add a shipping carrier, tracking information, pick and pack, and so on. If **Enable Fulfilment Webhook** is enabled then a webhook is set up in Onport by the integration and all the fulfillment details are stored in Commerce.

The integration also creates a custom flow with a slug as `fulfilment_items` and the following fields are created in the flow:

- Order Item Id (orderitem_id)
- Fulfilled Quantity (fulfilled_quantity)
- Fulfilled SKU (fulfilled_sku)
- Total Quantity (total_quantity)
- Tracking URL (tracking_url)
- Label URL (label_url)
- Tracking Number (tracking_number)
- External Instance ID (instance_id)
- External Fulfilment ID (fulfilment_id)

An `order` level flow and fields are created as follows:

- Fulfillments (fulfillments)
- Partially Fulfilled (partially_fulfilled)

An `order_items` level flow and fields are created as follows:

- Fulfilled Quantity (fulfilled_quantity)
- Fulfilment Status (fulfilment_status)

### Pre and Post Processors - Fulfilment
There is pre and post processor configuration for fulfilment. This is where you can configure external endpoints to do any pre or post processing. For example, if you have an external system that can send dispatch emails with tracking information then add the endpoint as part post processor.

## Synchronizing Onport Cancellation Data With Commerce

During the fulfillment process, vendors can cancel partial orders or complete orders. If the **Enable Order/Item Cancellation Webhook** is enabled then the cancellation is processed in Commerce.

:::note
A Webhook in Onport needs to be set up manually. 

1. Log in into Onport.
2. Select **Integrations**.
3. Select **API**.
4. Provide a URL.
5. Select **TRIGGER WHEN AN ACTION IS TRIGGERED ON AN INSTANCE**. 
6. In **Resource**, select **Purchases**. 
7. In **Instance Method**, select **Cancel**. 
8. Select **Add Webhook**.
:::

The integration also creates custom flow with slug as `cancelled_items` and following fields are created in this flow:

- Order Item Id (orderitem_id)
- Cancelled Quantity (cancelled_quantity)
- Total Quantity (total_quantity)
- External Instance ID (instance_id)
- External Sale Return ID (sale_return_id)
- Refund Amount (refund_amount)

An `order` level flow and fields are created as follows:

- Cancellations (cancellations)
- Partially Cancelled (partially_cancelled)

An `order_items` level flow and fields are created as follows:

- Cancelled Quantity (cancelled_quantity)
- Cancellation Status (cancellation_status)

### Pre and Post Processors - Cancellation
There is pre and post-processor configuration for cancellation. This is where you can configure external endpoints to do any pre or post-processing. For example, if you have an external system that can send cancellation emails or refund the cancelled item amount then add the endpoint as part post-processor.

## Order and Shipping Status in Commerce

- When all the items/quantities in the order are shipped then shipping status in Commerce is changed to `fulfilled`.
- When all the items/quantities in the order are cancelled then the order status in Commerce is changed to `cancelled`.
- When only a few items/quantities are shipped then the order and shipping status in Commerce is not changed, but `partially_fulfilled` is `true` on the order level.
- When some of the items/quantities are shipped, some are cancelled, and some still require action from the vendor, then the order and shipping status in Commerce is not changed, but `partially_fulfilled` and `partially_cancelled` is `true` on the order level.
- When some items/quantities are shipped and the remaining are cancelled, meaning the vendor has taken action on the remaining items/quantities, then the order status does not change but the shipping status in Commerce is changed to `fulfilled`. In addition, `partially_cancelled` remains `true` on order level.

## Prerequisites

You must have completed the following tasks in Onport before configuring the integration in Commerce.

### Create an Onport Channel ID

You must provide a custom Onport **Channel ID** when you are configuring the  Onport Integration in **Integrations Hub**. See [Onport Dev Docs](https://composable.jetti.io/).

1. Login to Onport.
1. Go to **Integrations**.
1. Click **Custom Channel** to create a new custom channel. The **Channel ID** forms part of the custom channel URL, once the custom channel is created.

### Retrieve the Onport Custom Channel ID

Once you have created a custom channel ID, you must retrieve it using `GET /custom-channels/<id>.json` from the Onport Custom Channel API where *id* is the channel ID that forms part of the channel URL that you created above. An example response is shown below.

```json
{
  "id": 143,
  "companyId": "3001",
  "channelId": 5365,
  "name": "Commerce",
  "resourceLocation": "null"
}
```

## Collecting Your Setup Information

Before you begin configuring your Onport integration in Commerce Manager, you need to collect the necessary setup information from Onport and Commerce Manager.

### Collecting Onport Setup Information

Collect the following setup information from Onport.

| Option | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Onport API Base URL. Default value is `https://api.jetti.io/api`. |
| **API Key**                       | Your Onport API Key. |

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Configuring the Onport Integration

Once you have:

- [Understood the prerequisites](#prerequisites).
- [Collected your setup information](#collecting-your-setup-information).

You are ready to configure the Onport integration in **Integrations Hub**.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Order Management, Marketplace and Inventory Integrations**, click **Onport Integration**. The **Onport** integration guides you through the steps you need to follow to complete the integration.
1. Click **Next**. The **Trigger details** consist of some details about the **Onport** integration.
1. Click **Next**. The **Connection** page is displayed.
1. Complete the information in the **Connection** page.

    - **Client-ID**  - Your Commerce Client ID.
    - **Client-Secret** - Your Commerce Client Secret.
    - **Token URL** - Your Commerce API Token URL.

1. Click **Connect** to make sure that the authentication is completed successfully.
1. Complete the **Onport Connection** credentials.

    - **API Base URL**  - Your Onport API Base URL. Default value is `https://api.jetti.io/api`.
    - **API Key** - Your Onport API Key.

1. In **Onport Channel ID**, provide your Onport Channel ID. See [Create an Onport Channel ID](#create-an-onport-channel-id).
1. Click **Next**. The **Webhook Setup** page is displayed. From this page, decide which webhooks you want to set-up, depending on your requirements. The Onport Integration automatically creates the webhooks, once you have finished configuring the integration.

    :::caution
    Do not change any API keys for the webhooks. The webhooks are authorized using the `configuration.secret_key` value in the request body. Configuring an API key directly on a webhook results in a non-functional integration.
    :::

    | Option                                                      | Required | Description                                                                                                                                               |
    |-------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Enable Order Webhook**                                    | Optional | Turn on the **Enable Order Webhook** toggle if you want orders in Commerce to be integrated with Onport.                                                  |
    | **Enable Pre Processor Webhook (Order)**                    | Optional | Turn on the **Enable Pre Processor Webhook (Order)** toggle and provide an **Endpoint URL** if you want any pre processors for orders.                    |
    | **Enable Post Processor Webhook (Order)**                   | Optional | Turn on the **Enable Post Processor Webhook (Order)** toggle and provide an **Endpoint URL** if you want any post processors for orders.                  |
    | **Enable Fulfilment Webhook**                               | Optional | Turn on the **Enable Fulfilment Webhook (Order)** toggle if you want fulfillments in Onport to be integrated with Commerce.                               |
    | **Enable Pre Processor Webhook (Fulfilment)**               | Optional | Turn on the **Enable Pre Processor Webhook (Fulfilment)** toggle and provide an **Endpoint URL** if you want any pre processors for fulfilment.           |
    | **Enable Post Processor Webhook (Fulfilment)**              | Optional | Turn on the **Enable Post Processor Webhook (Fulfilment)** toggle and provide an **Endpoint URL** if you want any post processors for orders.             |  
    | **Enable Order/Item Cancellation Webhook**                  | Optional | Turn on the **Enable Order/Item Cancellation Webhook** toggle if you want order or item cancellation in Onport to be integrated with Commerce.            |
    | **Enable Pre Processor Webhook (Order/Item Cancellation)**  | Optional | Turn on the **Enable Pre Processor Webhook (Order/Item Cancellation)** and provide an **Endpoint URL** if you want any pre processors for cancellation.   |
    | **Enable Post Processor Webhook (Order/Item Cancellation)** | Optional | Turn on the **Enable Post Processor Webhook (Order/Item Cancellation)** and provide an **Endpoint URL** if you want any post processors for cancellation. |
    | **Enable Product Webhook**                                  | Optional | Turn on the **Enable Product Webhook** toggle if you want product updates in Onport to update product data in Commerce.                                   |
    | **Enable Pre Processor Webhook (Product)**                  | Optional | Turn on the **Enable Pre Processor Webhook (Product)** and provide an  **Endpoint URL** if you want any pre processors for products.                      |
    | **Enable Post Processor Webhook (Product)**                 | Optional | Turn on the **Enable Post Processor Webhook (Product)** and provide an  **Endpoint URL** if you want any post processors for products.                    |
    | **Enable Inventory Webhook** | Optional | Turn on the **Enable Inventory Webhook** toggle if you want inventory changes in Onport to increment or decrement inventory in Commerce.                  |
    | **Enable Price Webhook** | Optional | Turn on the **Enable Price Webhook** toggle if you want price changes in Onport to change price information in Commerce.                                  | 

1. *Applies to **Enable Order Webhook** only*. You must specify the order events that you want to generate webhook events for. 
    1. In **Order Events**, select the events from the **Value** list. 
    1. Select **+Add value** to add more events. You can select one or all of the following:

       - `order.created`
       - `order.updated`
       - `order.fulfilled`
       - `order.paid`
       - `order.authorized`

   1. Add an **Onport Custom Channel ID**. See [Retrieve the Onport Custom Channel ID](#retrieve-the-onport-custom-channel-id)
   1. Add a secure API key as part of **Elastic Path Webhook API Key**. This is the `secret_key` used when setting up the order webhook in Elastic Path.

1. Click **Next**. The **Templates** configuration page is displayed. 
1. Click **Edit** for the request template you want to edit. See [Synchronizing Onport Product Data With Commerce Product Data](#synchonizing-onport-product-data-with-commerce-product-data), [Synchronizing Commerce Order Data With Onport Order Data](#synchronizing-commerce-order-data-with-onport-order-data) and [Synchronizing Onport Price Data With Commerce](#synchronizing-onport-price-data-with-commerce).
1. Click **Next**. The **Config** configuration page is displayed. 
1. (Optional) If you want to exclude any SKUs from the fulfillment or cancellation process then add the SKUs. For example, you must exclude your shipping-related SKUs.
1. Select the price book whose price you want to add or update.
1. Click **Finish**. Your integration is enabled.

## Using Onport Integration

To change any configuration details in your Onport integration, open your Onport Integration and go to **Summary** > **Reconfigure**.

In addition, from **Summary**, you can view, pause or delete your Onport integration.

If there is an update to the Commerce Onport integration, a message is displayed in **Summary**. Click **Update** to update your integration. You are guided through the steps to configure your integration.

## How To Get Fulfilment And Cancellation Data On Commerce Order API

Use the [Get An Order](/docs/api/carts/get-an-order/) API with include as `include=fullfilments,items,cancellations` to retrieve fulfillment and cancellation data for Commerce orders.

## Troubleshooting the Onport Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

From **Step Outputs**, you can select a step to see its output. You can retry an individual step.

---

## Integrating with OpenAI Product Description Rewrite

You can integrate Commerce with OpenAI quickly by adding your credentials and deploying the OpenAI Product Description Rewrite integration in **Integrations Hub** of Commerce Manager. Using the OpenAI Product Description Rewrite integration, you can rewrite your Commerce product descriptions. Using the instructions you provide, OpenAI drafts a new product description and adds it to an extended field on your product. 

## Collecting Your Setup Information

Before you begin configuring your integration in Commerce Manager, you need to collect the necessary setup information from OpenAI and Commerce Manager.

:::caution
Collect the following information and make sure you have it available, for example, in a text file, before configuring your integration in Commerce Manager. If you leave the Integration page in Commerce Manager, the integration is not saved and you must remove the integration and create a new one.
:::

### Collecting OpenAI Setup Information

You need to collect the API Key and Organization ID from OpenAI.

To collect the API Key:

1. Go to OpenAI.
1. Select your username.
1. Select **View API Keys**.
1. Select **Create New Security Key**.
1. Copy the newly-created API key.

To collect the Organization ID:

1. Go to OpenAI.
1. Select your user image.
1. Select **Manage Account**.
1. Select **Settings**.
1. Copy your organization ID.

### Collecting Commerce Manager Setup Information

1. Log in to Commerce Manager as a user with Seller Admin privileges.
1. Go to **SYSTEM** > **Application Keys**.
1. Select **Create New**.
1. Type a name for your application key.
1. Select **Create**.
1. Select **Dismiss** to view your application key. 
1. To configure the integration, you need to copy the following values:

    | Commerce API Key | Description                            |
    |:------------------------------------|:---------------------------------------|
    | **API Base URL**                    | Your Commerce API Base URL. |
    | **Client ID**                       | Your Commerce Client ID. |
    | **Client Secret**                   | Your Commerce Client Secret. | | Your Commerce Client Secret. |

See [Creating an Application Key in Commerce Manager](/docs/commerce-manager/application-keys/application-keys-cm).

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Configuring the Integration

Now that you've collected the setup information, let's begin by configuring the integration.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Product Information**, click on the **OpenAI Product Description Rewrite** integration.
1. Review the **Overview** page and click **Configure**. The Trigger details are displayed.
1. Click **Next**.
1. Configure the following information and click **Finish**. 

| Configuration parameter | Value |
|:----|:---- |
| **epcc_base_url** | Your Commerce API Token URL. For example, `useast.api.elasticpath.com/oauth/access_token` (EU) or `useast.api.elasticpath.com/oauth/access_token` (US). See [Regions and URLs](/guides/Getting-Started/elastic-path-domains#regions-and-urls). |
| **epcc_client_id** | Your Commerce API Client ID. |
| **epcc_client_secret** | Your Commerce Client Secret. |
| **API Key** | Your OpenAI connection API key. |
| **Organization** | Your OpenAI connection organization ID. |
| **ai_instructions** | The instructions that you want to use to rewrite your product descriptions. |
| **ai_model** | Your AI model. |

## Using the Integration

To rewrite a product description: 

1. From the OpenAI Description Rewrite integration, select **Test**.
1. In **Payload body**, enter the product ID of the products whose description you want to update. You can only rewrite one product's description at a time. 

    ```json
     {
       "product": {
     		"product_id": "b8e9af84-69f9-472c-ad18-57557e1d2c75"
   	      }
     }
    ```
    
    You can get a product's ID from the [Products page](/docs/commerce-manager/product-experience-manager/products/view-product-details) in Commerce Manager or using the [Get all Products](/docs/api/pxm/products/get-all-products) endpoint.

1. Click **Save & Run Test**.
1. When the test has finished, go to your store to see your extended product descriptions. 
1. To rewrite the product description of another product, amend the **ai_instructions**, add a new product ID to the **Payload body** and run **Test** again.

---

## Integrating with Pimberly

You can quickly and easily integrate Commerce with Pimberly using the **Integrations Hub** in Commerce Manager. Integrating Pimberly with Commerce means you can synchronize catalog data such as products, price, images, and categories between Commerce and Pimberly. 

You can also migrate your catalog data related information to Commerce as this integration can load all the data from Pimberly.

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Collecting your Setup Information

### Collecting Pimberly Setup Information

Collect the following setup information from Pimberly.

| Option | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Pimberly API Base URL. Default value is `https://sandbox.pimber.ly/api/v2.2`. |
| **API Key**                       | Your Pimberly API Key. Login to your Pimberly account to retrieve your API Keys. |
| **Webhook URL**               | Your Pimberly webhook URL. Default value is `https://sandbox-api.pimberly.io`. |

### Collecting Commerce Manager Setup Information

To create a new [application key](/docs/commerce-manager/application-keys/application-keys-cm), go to **SYSTEM > Application Keys**.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **Token URL**                       | Your Commerce API token URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Synchronizing from Pimberly to Commerce

As part of the Pimberly Integration, changes in catalog data in Pimberly automatically updates catalog data in Commerce.

![Pimberly to Elastic Path Flow](/assets/Pimberly.png)

### Prerequisites

 - Ensure that you have [collected your setup Information](#collecting-your-setup-information).
 - Ensure that you have created a template for [price book](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks#creating-price-books), [hierarchies](/docs/commerce-manager/product-experience-manager/hierarchies/creating_hierarchies), [templates](/docs/commerce-manager/product-experience-manager/extending-products/templates#creating-templates), and [Variations](/docs/commerce-manager/product-experience-manager/variations#creating-variations) in Commerce Manager.

 ### Procedure

1. In Commerce Manager, go to **COMPOSER > Integrations Hub**.
1. Under **Product Information**, click **Pimberly**.
1. Click **Configure**. The Pimberly integration guides you through the steps you need to follow to complete the integration.
1. Click **Next**. The **Connection** page is displayed.
1. On **Connection** page, do the following:
    1. Complete the **Commerce Connection** credential details:
        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.
        - **Token URL** - Your Commerce API Token URL
    
    1. Click **Connect**. The authorization is successfully completed.
    1. Complete the **Pimberly Connection** credential details:
        - **API Key** - Your Pimberly API Key.
        - **API Base URL**  - Your Pimberly API Base URL. Default value is `https://sandbox.pimber.ly/api/v2.2`
        - **Webhook URL** - Your Pimberly Webhook URL. Default value is `https://sandbox-api.pimberly.io`

1. Click **Next**. The **Configuration** page is displayed. 

    The **Enable Webhook Setup** toggle is always enabled by default to automatically enable webhook in Pimberly. 
1. In the **Value** fields, under the **Webhook Actions** section, **create** and **update** actions are set by default.
    
    You can set up your webhook actions depending on your requirements. For example, if you only want to publish a message when a product is updated, then delete **create** from the **Value** field.
    
1. (Optional) To add move values, click **+Add value**. 
1. (Optional) If you want to trigger full sync, turn on the **Enable Full Sync** toggle. The full sync will be triggered as per the **Full Sync Cron Job Time**. It is disabled by default.
    :::note
    Default value of **Full Sync Cron Job Time** is `0 0 31 12`. You can set your own time to run the full sync periodically.
    :::
1. Click **Next**.  The **Templates** page is displayed.
1. Click **Edit** under the **Product Template**.
1. Update the **Product Template** to map the Commerce product templates and attributes to Pimberly.
    For example, suppose you want to import pimberly field `Feature-1` and `Feature-2` attributes into Commerce Manager. You need to update the corresponding `templateSlug` and `fieldSlug` fields to represent attribute slug in Commerce.
    
    The following example shows how this should look in the Product Template.

```Json
    "attributes":[[
    {
        "templateSlug":"products(extension)",
        "templateAttributes": [
            [
                $merge([
                    ($.'Feature 1' ?
                        {
                            "fieldSlug":"feature1",
                            "type":"string",
                            "value":$.'Feature 1'
                        } : {}
                    )
                ]),
                $merge([
                    ($.'Feature 2' ?
                        {
                            "fieldSlug":"feature2",
                            "type":"string",
                            "value":$.'Feature 2'
                        } : {}
                    )
                ])
            ]  ~> $filter(function($v, $i, $a) {
                $v.value
            })
        ]
    }
]] ~> $filter(function($v, $i, $a) {
        $count($v.templateAttributes) > 0
})
```

1. Click **Edit** under the **Node Template**.
1. Update the name of the hierarchy created in Commerce in the `hierarchySlug` field.
    
    For example:
    
    ```Json
    "hierarchySlug": "uk-hierarchy"
    ```
1. Click **Edit** under **Price Template**.
1. Update the price book name of Commerce in `priceBookName` field. For example, if the price book name is `UKandIEPricebook` in Commerce cloud, update the same in the **Price Template**.

    For example:
    ```Json
    "priceBookName": "UKandIEPricebook"
    ```
1. Click **Edit** under the **Variation Template**.
1. Update the variation template to map with the Commerce. This is similar to Product Template. If you make any changes in Product, you need to make similar changes in Variations as well.
1. Click **Next**. The **Field Settings** page is displayed.
1. In the **Child Product Field**, the default value is Pimberly is `Items`. Update this field if you change this in Pimberly.
1. In the **Parent Product Field**, the default value in Pimberly is `Parents`. Update this field if you change this in Pimberly.
1. In the **Product Type Field**, the default value in Pimberly is `Product Type`. Update this field if you change this in Pimberly.
1. In the **Parent Product Type** field, the default value in Pimberly is `Product`. Update this field if you change this in Pimberly.
1. In the **SKU Product Type** field, the default value in Pimberly is `SKU`. Update this field if you change this in Pimberly.
1. Click **Finish**. Your integration is enabled. The webhook will be triggered successfully, and you can see the trigger details in Commerce Manager.

## Demos

Watch the following video to learn how to synchronize your catalog data from Pimberly to Commerce:

<iframe width="560" height="315" src="https://www.youtube.com/embed/H61cCbjWtiE" title="Configuring Pimberly" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with Salsify

You can quickly and easily integrate Commerce with Salsify using the **Integrations Hub** in Commerce Manager. Integrating Salsify with Commerce means you can synchronize catalog data such as products, price, images, and categories between Commerce and Salsify.

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Collecting your Setup Information

### Collecting Salsify Setup Information

Collect the following setup information from Salsify.

| Option | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Salsify API Base URL. Default value is `https://app.salsify.com/api/v1/orgs/`. |
| **API Key**                       | Your Salsify API Key. To collect your API key, log in to your Salsify account, go to **My Profile > API Access**, and click **Show API Key**. |
| **Organization ID**               | Your Salsify Organization ID. |

### Collecting Commerce Manager Setup Information

To create a new [application key](/docs/commerce-manager/application-keys/application-keys-cm), go to **SYSTEM > Application Keys**.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **Token URL**                       | Your Commerce API token URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

## Synchronizing from Salsify to Commerce

As part of the Salsify Integration, changes in Catalog data in Salsify automatically updates catalog data in Commerce, and vice versa.

![Salsify to Elastic Path Flow](/assets/Salsify-to-Elastic-Path.png)

### Prerequisites

 - Ensure that you have [collected your setup Information](#collecting-your-setup-information).
 - Ensure that you have created a [price book](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks#creating-price-books), [hierarchies](/docs/commerce-manager/product-experience-manager/hierarchies/creating_hierarchies), and [templates](/docs/commerce-manager/product-experience-manager/extending-products/templates#creating-templates) in Commerce Manager.

 ### Procedure

1. In Commerce Manager, go to **COMPOSER > Integrations Hub**.
1. Under **Product Information**, click **Salsify**
1. Click **Configure**. The Salsify integration guides you through the steps you need to follow to complete the integration.
1. Click **Next**. The **Connection** page is displayed.
1. On the **Connection** page, do the following:
    1. Complete the **Commerce Connection** credential details:
        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.
        - **Token URL** - Your Commerce API Token URL

    1. Click **Connect**. The authorization is successfully completed.
    1. Complete the **Salsify Connection** credentials:
        - **API Key** - Your Salsify API Key.
        - **Org Id** - Your Salsify Organization ID.
        - **API Base URL**  - Your Salsify API Base URL. Default value is `https://app.salsify.com/api/v1/orgs/`.

1. Click **Next**. The **Templates** page is displayed. 

    You can use templates to send your custom data or attributes to another system using JSON data.
1. Click **Edit** under **ElasticPath Product Template**.
1. Update the **Product Template** to map the Commerce product templates and attributes to Salsify.
    
    For example, suppose you want to import Salsify field brand and Feature-2 attributes into commerce Manager. You need to update `templateSlug` and `fieldSlug` fields to represent attribute slug in Commerce.

    The following example shows how this should look in the Product Template.

    ```Json
    "attributes":[
    [
        {
            "templateSlug":"products(extension)",
            "templateAttributes":[
                [
                    $merge([
                        ($product.Brand ?
                            {
                                "fieldSlug":"brand",
                                "type":"string",
                                "value":$product.Brand
                            }
                        )
                    ]),
                    $merge([
                        ($product.'Feature-2' ?
                            {
                                "fieldSlug":"feature2",
                                "type":"string",
                                "value":$product.'Feature 2'
                            }
                        )
                    ])
                ]  ~> $filter(function($v, $i, $a) {
                    $v.value
                })
            ]
        }
    ]
    ] ~> $filter(function($v, $i, $a) {
        $count($v.templateAttributes) > 0
    })
    ``` 

1. Click **Edit** under **ElasticPath Price Template**. Update the price book name of Commerce in `priceBookName` field. For example, if the price book name is `UKandIEPricebook` in Commerce cloud, update the same in the **Price Template**.
    For example: 

    ```Json
    "priceBookName": "UKandIEPricebook"
    ```
1. Click **Edit** under **ElasticPath Node Template**. Update the name of the hierarchy created in Commerce in the `hierarchySlug` field.
    For example:

    ```Json
    "hierarchySlug": "uk-hierarchy"
    ```

1. Click **Next**. The **Configuration** page is displayed.
    
    **Enable Salsify to Elastic Path Sync**, **Enable Salsify Event - Product Creation**, and **Enable Salsify Event - Product Updates** are enabled by default to automatically synchronize from Salsify to Commerce.

1. (Optional) If you want to trigger full sync, turn on the **Enable Full Sync Scheduler** toggle. The full sync will be triggered as per the **Full Sync Cron Job Time**. By default it is disabled.
        :::note
        Default value of **Full Sync Cron Job Time** is `0 0 31 12`. You can set your own time to run the full sync periodically.
        :::
1. Click **Finish**. Your integration is enabled.

## Synchronizing from Commerce to Salsify

As part of the Salsify Integration, changes in catalog data in Commerce automatically updates catalog data in Salsify, and and vice versa.

![Elastic Path to Salsify Flow](/assets/Elastic-Path-to-Salsify.png)

### Prerequisites

Ensure that you have [collected your setup Information](#collecting-your-setup-information).

### Procedure

1. Log in to Salsify account.
1. Go to **More > Properties**. The **Properties Page** is displayed.
1. To create a new property, go to **Actions > New Property**. The **Create Property** page is displayed. 
1. Enter the **Name** and **Data Type**, and click **Save**. You can create as many properties as you want to. 
1. In Commerce Manager, go to **COMPOSER > Integrations Hub**.
1. Under **Product Information**, click **Salsify**.
1. Click **Configure**.
1. Click **Next**. The **Connection** page is displayed.
1. On **Connection** page, do the following:
    1. Complete the **Commerce Connection** credential details:
        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.
        - **Token URL** - Your Commerce API Token URL

    1. Click **Connect**. The authorization is successfully completed.
    1. Complete the **Salsify Connection** credentials:
        - **API Key** - Your Salsify API Key.
        - **Org Id** - Your Salsify Organization ID.
        - **API Base URL**  - Your Salsify API Base URL. Default value is `https://app.salsify.com/api/v1/orgs/`.

1. Click **Next**. The **Templates** page is displayed.
1. Click **Edit** under the **Salsify Product Template**.
1. Update the **Salsify Product Template** with new properties that you have created in the **Create Property** page in Salsify account.
    
    The following example illustrates mapping all the images from Commerce to `ImageMedium` field in Salsify.

    ```json
    "ImageMedium": [
        relationships.main_image.data.id,
        relationships.files.data.id
    ] ~> $filter(function($img) {
        $$.images[$.'salsify:id' = $img]
    })
    ```

1. Click **Next**. The **Configuration** page is displayed.

    **Enable Salsify to Elastic Path Sync**, **Enable Salsify Event - Product Creation**, and **Enable Salsify Event - Product Updates** toggles are enabled by default. You can disable these toggles if you don't want to synchronize from Salsify to Elastic Path.

1. (Optional) To automatically synchronize Elastic Path to Salsify, turn on the **Enable Elastic Path Sync to Salsify** toggle. It is disabled by default.
1. (Optional) If you want to trigger full sync, turn on the **Enable Full Sync Scheduler** toggle. The full sync will be triggered as per the **Full Sync Cron Job Time**. It is disabled by default.
    :::note
    Default value of **Full Sync Cron Job Time** is `0 0 31 12`. You can set your own time to run the full sync periodically.
    :::

1. Click **Finish**. Your integration is enabled.
1. In Commerce Manger, go to **SYSTEM> Store Settings > Webhooks** to see that the your webhook has been enabled.

## Demos

 Watch the following videos:

<iframe width="560" height="315" src="https://www.youtube.com/embed/uxM0bGrqnDQ" title="Salsify to Commerce Configuration" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

<iframe width="560" height="315" src="https://www.youtube.com/embed/Iv0eOuuzIpM" title="Commerce to Salsify Configuration" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with Shopify

You can quickly and easily integrate Shopify with Commerce using the **Integrations Hub** in Commerce Manager. Integrating Shopify with Commerce enables you to synchronize your Shopify store catalog and inventory data with Commerce. Once this data is accessible in Product Experience Manager, you can elevate your merchandiser experience, creating distinctive product encounters that exceed customer expectations and stimulate growth.

![Shopify Integration](/assets/shopify.png)

## Understanding how the Shopify Integration Works

The Shopify Integration ensures a seamless synchronization of catalog information such as products, prices, images, variations, templates, attributes and categories from Shopify to Elastic Path. This integration supports incremental updates through webhooks and offers the option of a full sync, allowing the migration of all catalog data into Elastic Path. By default, the full sync is disabled, but you can enable this and also define cron job timings. The full sync functionality and webhook-based integration also allows you to sync your inventory information from Shopify to Elastic Path.

Additionally, the bundle sync feature enables you to create bundles in Elastic Path, automatically generating them in Shopify upon catalog publication. The bundle details, such as name, description, and image, are only synced in Shopify. This feature is available by default, and you have the flexibility to customize syncing preferences with available configuration options.

## Shopify Integration Templates

The Shopify integration uses the following request templates that contain all parameters required for the Shopify integration to function correctly. The Shopify integration provides default templates. However, when configuring the integration, you can edit these templates to change or add any additional parameters depending on your business requirements. The templates use [JSONata](https://docs.jsonata.org/overview.html).

The following table describes the templates available.

| Template | Description |
| :--------| :------------|
| **ElasticPath Product Template** | This template defines the product information you want to synchronize from Shopify to Elastic Path. The default template loads product data from Shopify to Elastic Path. You can change this template based on your business needs. |
| **ElasticPath Price Template** | This template specifies how prices are synchronized from Shopify to Elastic Path. Do not change the `priceBookName` field in the template. You can change this template based on your business requirements.|
| **ElasticPath Node Template** | This template applies only if **Enable Category Sync** is enabled. You can add nodes in different locales. When selecting a hierarchy, do not change the `hierarchySlug` field in the template. You can change this template based on your business needs. |
| **Shopify Get Product Query** | Shopify GraphQL APIs is used to fetch product information from Shopify. The default product query is included in the configuration, but you can change it based on your business needs. Refer to [Product Query Shopify Documentation](https://shopify.dev/docs/api/admin-graphql/2023-10/queries/product) to make changes. The configuration of the Elastic Path Product Template relies on the output of this query to transform product requests for Elastic Path. |

## Prerequisites

### Collecting Commerce Manager setup information

Collect the following Commerce API keys. When you log in to Commerce Manager as a Seller Admin, you can find this information in **SYSTEM** > **Application Keys** in Commerce Manager. Also see how to create a [new application key](/docs/commerce-manager/application-keys/application-keys-cm).

| Commerce API Key                   | Description                                    |
|:-----------------------------------|:-----------------------------------------------|
| **Client ID**                      | Your Commerce Client ID.                       |
| **Client Secret**                  | Your Commerce Client Secret.                   |
| **Token URL**                      | Your Commerce API token URL.                   |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

### Collecting Shopify connection details

You must collect the following details from Shopify store:

| Option | Description |
|:-------|:------------|
| **Host** | Your domain of your Shopify platform without `https://`. For example, `<YOUR_STORE>.myshopify.com`. |
| **Admin API Access Token** | Admin access token generated by your Shopify custom app. See [Shopify Custom App Installation](#shopify-custom-app-installation). | 

### Shopify Custom App Installation

Follow these steps to generate **Admin API Access Token**.

1. Log into your Shopify admin console.
1. Go to **Settings** > **Apps and sales channel**.
1. Select **Develop apps**.
1. Select **Create an app**.
1. In the **App name** field, enter the name for your App.
1. Select **Create app**.
1. Under the **Overview** tab, select **Configure Admin API scopes**.
1. Under the **Configuration** tab, select the following checkboxes:
    - **read_inventory**
    - **read_products**
    - **write_products**
1. Select **Save**.
1. Select **Install app**. Once the app is created, you can see the Admin API access token under the **API Credentials** tab. You can reveal your access token only once so make sure to copy your access token and paste it in the Shopify Integration.

## Configuring Shopify Integration

Before you begin ensure that you have created a [price book](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks#creating-price-books) and a [hierarchy](/docs/commerce-manager/product-experience-manager/hierarchies/creating_hierarchies), and created and configured a [Catalog](/docs/commerce-manager/product-experience-manager/catalogs/creating-catalogs) with this price book and hierarchy in Commerce Manager to hold the Shopify catalog data. Once you have completed the [Prerequisites](/docs/composer/integration-hub/product-information/shopify#prerequisites), you are ready to configure the Shopify integration.

1. In Commerce Manager, under **COMPOSER**, select **Integrations Hub**.
1. Under **Product Information**, select **Shopify**.
1. Select **Configure**. The integration guides you through the steps you need to follow.
1. Select **Next**. The **Connections** page is displayed.
1. Enter the following details in the **Elastic Path** section:

    - **Client ID**
    - **Client Secret**
    - **Token URL**

    For more information, see [Collecting Commerce Manager setup information](/docs/composer/integration-hub/product-information/shopify#collecting-commerce-manager-setup-information).

1. Enter the following details in the **Shopify** section:

    - **Host** 
    - **Admin API Access Token**

    For more information, see [Collecting Shopify connection details](/docs/composer/integration-hub/product-information/shopify#collecting-shopify-connection-details).

1. Select **Connect**. The authorization is successfully completed.

1. In the **Shopify API Version** field, enter your Shopify API Version.
1. Select **Next**. The **Template** page is displayed.
1. (Optional) Edit the templates on the **Template** page. See [Shopify Integration Templates](/docs/composer/integration-hub/product-information/shopify#shopify-integration-templates).
1. Select **Next**. 
1. In the **Select Catalog** field, choose the placeholder catalog you created prior to the integration configuration.
1. In the **Select Pricebook** field, choose the placeholder price book you created prior to the integration configuration.
1. Select the **Enable Category Sync** checkbox to sync categories from Shopify to Elastic Path. It is enabled by default. This means that collections are created as nodes in the hierarchy selected in Elastic Path and products are associated to these nodes.

    You may choose not to retrieve category information from Shopify if you are planning to use Product Experience Manager to set up a multi-tier taxonomy. In such cases, you can disable this configuration.

1. In the **Select Hierarchy** field, choose the placeholder hierarchy you created prior to the integration configuration. If you do not turn on **Enable Category Sync**, you do not have the option to choose a hierarchy.
1. Select the **Enable Inventory Sync(Shopify to Elastic Path)** checkbox to sync inventory from Shopify to Elastic Path. It is enabled by default. This means that as part of a full load, inventory information are also loaded along with product data. 

    If this configuration is enabled, a **INVENTORY_LEVELS_UPDATE** webhook event type is created in Shopify. If this configuration is disabled, inventory information is not synced from Shopify to Elastic Path.
1. Select the **Enable Bundle Sync(Elastic Path to Shopify)** checkbox to sync bundles from Elastic Path to Shopify. You can create bundles in Commerce Manager after loading all products from Shopify to Elastic Path. It is enabled by default.
1. Select the **Enable Full Sync(Shopify to Elastic Path)** checkbox to enable full sync capabilities from Shopify to Elastic Path, including products, prices, images, variations, templates, attributes, categories, and inventory. Full sync can be triggered by manually running the URL endpoint or by enabling the scheduler. Delta syncs are enabled by default.
1. Select the **Full Sync Scheduler (Shopify to Elastic Path)** checkbox to run the full sync periodically. The field is activated only when **Enable Full Sync(Shopify to Elastic Path)** is enabled. The default time is every 15 minutes, but you can change it based on your business requirements.
1. Select **Finish**. Your integration is now enabled, and you can see the following changes: 
    - In Commerce Manger, go to **Product Experience Manger** > **Configurations**, you can see that all templates and attributes have been loaded from Shopify.
    - In Commerce Manger, under **SYSTEM**, go to **Store  settings** > **Webhooks** to see that your webhooks specific for Bundles sync from Elastic Path to Shopify have been enabled.
    - Go to your Shopify store and ensure that the following webhooks have been created:
        - **PRODUCTS_CREATE** event: Notifies Elastic Path when a new product is created in Shopify.
        - **PRODUCTS_UPDATE** event: Notifies Elastic Path when an existing product is updated in Shopify.
        - **PRODUCTS_DELETE** event: Notifies Elastic Path when an existing product is deleted in Shopify.
        - **INVENTORY_LEVELS_UPDATE** event:  Notifies Elastic Path whenever the inventory level is changed in Shopify. This webhook is created only if **Enable Inventory Sync** is turned on.
        - **COLLECTIONS_UPDATE** event: Notifies Elastic Path whenever there is any change in a collection in Shopify. For example, if a new collection is created or products are associated with an existing collection. This webhook is created only if **Enable Category Sync** is turned on.

## Using Shopify Integration

Once the integration is enabled and your Shopify catalog data is synchronized with Commerce, your catalog becomes visible on your storefront upon publishing. If you have set a **Full Sync Scheduler (Shopify to Elastic Path)**, it automatically triggers at the defined time to run the full sync. Alternatively, you can follow these steps to manually trigger the full sync.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Select the Shopify integration.
1. Under **Trigger Details**, select **_Inbound product (Full Load)**. This option is visible only if you select the **Enable Full Sync(Shopify to Elastic Path)** checkbox.
1. Copy the URL link and paste it in the browser. This triggers a full load of all products, categories, if **Enable Category Sync** is enabled, prices, templates, variations, and images from Shopify to Elastic Path.
1. Go to **Catalogs** and publish your catalog so you can see all the information in your Elastic Path storefront. See [Publishing Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs#publishing-catalogs). 
     If you did not turn on **Enable Category Sync**, you need to create your own multi-tier taxonomy using hierarchies and nodes, and associate those hierarchies with your catalog before publishing.

1. Once the catalog data is visible on your storefront, you can add products to your cart and checkout.

### Use case scenario 1: setting up a sale price.

You can set up a sale price for a product in Commerce Manager. To do this, perform the following steps:

1. In Commerce Manager, under **Product Experience Manager**, select **Products**. 
1. Select the product from the list that you want to set up a sale price.
1. select **+ Add Sale Price**, and do the following:
    1. To associate the option with a price book, from Price Book list, select a price book.
    1. In **Sale Name**, enter a name for your sale.
    1. (Optional) From **Start Date / Time - End Date / Time**, select a start date and time and an end date and time of the sale.
    1. Enter a price for each of the available currencies. You can add currencies under **SYSTEM** in **Store Settings > Currencies**.
    1. Select **Add Sale**.
    1. Publish your catalog again. See [Publishing Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs#publishing-catalogs).
    1. Go to your storefront to see the new sale price for that product.

### Use case scenario 2: creating a new bundle
   
1. In Commerce Manager, under **Product Experience Manager**, select **Products**.
1. Create a new bundle product. See [Bundles in Commerce Manager](/docs/commerce-manager/product-experience-manager/bundles/bundle-configuration).
1. Publish your catalog. See [Publishing Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs#publishing-catalogs).
    
    You can now see that the newly created bundle has been added to your Shopify store. Note that any changes made to the bundle in the Shopify store are not synchronized back to Elastic Path.
1. Associate this product with the sales channel in your Shopify store. To do this: 
    1. Go to **Publishing** section on the right pane, and select three dots associated with it.
    1. Select **storefront** checkbox.
    1. Select **Save**. You can now see the bundles in your Elastic Path storefront. You can add this item to your cart and proceed with the checkout process.

## Demo

Watch the following video to learn how to integrate Shopify with Commerce using the **Integrations Hub** in Commerce Manager:

<iframe width="560" height="315" src="https://www.youtube.com/embed/qu3qH8GBVGE" title="Integrating with Shopify" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with Yotpo

You can quickly and easily integrate Commerce with Yotpo using the **Integrations Hub** in Commerce Manager. Integration with Yotpo enables your customers to provide ratings and reviews in the storefront for the products they purchased. You can also sync the customer feedback with any search provider that you use; this displays the average customer ratings and reviews received for a product in the storefront.

## How the Yotpo Integration Works

This is how the integration of Commerce with Yotpo works.

1. Whenever you publish a catalog, all the products that are part of the publish are created/updated in Yotpo.

   The first time a catalog is published, a full publish of the catalog is performed. The second time a catalog is published, a delta publish is performed. This means only the changes since the last publish of a catalog are published.

   The first time you want to synchronize a catalog with Yotpo, a full publish of the catalog must be performed. If a catalog is already published, before you configured the Yotpo Integration, you should delete all releases of the catalog and publish the catalog again.

   If you do this, and you are using the same catalog in other integrations, then this causes all the products in your other integrations to also be created again. For example, if you are using the catalog with an Algolia integration then all the products are synced with Algolia again.

2. The following Commerce information is shared with Yotpo:

    * Products:

        * Products with child products
        * Products with no child products
        * Child products

    * Orders: Both `order.created` and `order.fulfilled` information is synced with Yotpo.
    * Customers

3. Average ratings and total number of reviews received for a product in Yotpo are shared with Elastic Path Commerce Cloud, and stored with the relevant product as template data.

:::note
When a customer places an order in your storefront, an email is sent to the customer for providing feedback on the products purchased. This email is sent after a specific number of days; you can configure the time in Yotpo.
:::

## Prerequisites

You must complete the following before configuring the integration with Yotpo.

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. When you log in to Commerce Manager as a Seller Admin, you can find this information in **SYSTEM** > **Application Keys** in Commerce Manager.

| Commerce API Key                   | Description                                    |
|:-----------------------------------|:-----------------------------------------------|
| **API Base URL**                   | Your Commerce API Base URL.                    |
| **Client ID**                      | Your Commerce Client ID.                       |
| **Client Secret**                  | Your Commerce Client Secret.                   |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

### Collecting Yotpo connection details

You must get the following details from Yotpo:

| Option            | Description                                                                                            |
|:------------------|:-------------------------------------------------------------------------------------------------------|
| **Token URL**     | The API token URL of your Yotpo account. By default, the value is `https://api.yotpo.com/oauth/token`. |
| **Client ID**     | Your Yotpo Client ID. In Yotpo, it might be **Store ID**, **App ID**, or **App Key**.                  |
| **Client Secret** | Your Yotpo Client Secret.                                                                              |

## Configuring Yotpo Integration

Once you have completed the [Prerequisites](#prequisites), you are ready to configure the Yotpo integration:

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Under **Product Information**, click **Yotpo**.
3. Click **Configure**. The integration guides you through the steps you need to follow.
4. Click **Next**. The **Connections** pane is displayed.
5. Enter the following details in **Commerce Connection**:

    - **Client ID**
    - **Client Secret**
    - **Token URL**

   For more information, see [Commerce connection details](#commerce-cloud-connection-details).

6. Click **Connect**. The authorization is successfully completed.
7. In **Yotpo Connection**, enter the following values:

    - **Client ID**
    - **Client Secret**
    - **Client Token URL**

   For more information, see [Yotpo connection details](#yotpo-connection-details).

8. Click **Connect**. The authorization is successfully completed.
9. Click **Next**.
10. In **Configurations**, configure the following:

    | Configuration                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
    |---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Enable Catalog Selection Criteria** | Select this checkbox to either include or exclude catalogs from being published to Yotpo. You can specify multiple catalogs that you want to include or exclude from sharing with Yotpo. Select the **Enable Catalog Selection Criteria** checkbox.In the **Selection Rule** box, select `include` or `exclude`.Click [Add Multiple Catalogs to Yotpo](/assets/add-catalogs-yotpo.png) to add the catalogs that you want to include or exclude from publication.  You can add multiple catalogs to include or exclude from publication. **Note**: If you do not select this checkbox and specify your selection, all product catalogs are shared with Yotpo. |
    | **Enable Product Webhook**            | Select this checkbox to create webhook events for any product in Commerce. The product information is shared with Yotpo as part of this integration. By default, the checkbox is selected and `catalog-release.updated` event is created.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
    | **Enable Order Webhook** | Select this checkbox to create webhook events for orders in Commerce. The order details are shared with Yotpo as part of this integration. In the **Events** list, select the specific order event for which you want to create the webhook. For more information on order events, see [Observable Events](/docs/api/integrations/integrations-introduction#observable-events). By default, the checkbox is selected and the default event is `order.paid`. **Note**: In the **Events** list, we recommended that you select `order.fulfilled`. So, when a order is complete, a webhook event is generated in Commerce, and the order details are shared with Yotpo.                                            | 
    | **Enable Customer Webhook** | Select this checkbox if you want to create webhook events for customer information in Commerce. The customer details are shared with Yotpo as part of this integration. Click [Add Customer Events](/assets/add-customer-events-yotpo.png) to add the events for which you want to create webhooks in Commerce by default, `customer.selected` and `customer.updated` are added. You can remove these default events too and add specific customer events as per your requirements. For example, select `customer.deleted` if you want to disable customer status in Yotpo when a customer account is deleted in Commerce.                                                                       |

11. Click **Next**.
12. In **Templates**, you can find the default request templates that contain the parameters for the integration to function correctly. Depending on your requirements, you can edit the templates, adding any data that Yotpo supports. See [Yotpo Product API Documentation](https://core-api.yotpo.com/reference/products#product-properties).

    - **Product Template**

      This template is used to create and/or update product variants in Yotpo. Here is a snapshot of the default product template.
        
         ```json
        [
          $map(products, function($product) {
              {
                  "request": {
                      "sku": $product.attributes.sku,
                      "external_id": $product.id,
                      "name": $product.attributes.name,
                      "description": $product.attributes.description,
                      "status": $product.attributes.status = 'live' ? 'active' : 'draft',
                      "handle": $product.attributes.slug,
                      "image_url": $$.images[id=$product.relationships.main_image.data.id].link.href,
                      "custom_properties": {
                          "is_blocklisted": $product.attributes.status = 'live' ? false : true
                      }
                  },
                  "parent_product_id": $filter($product.attributes.base_product_id, function($e) { $e != '' })
              }
          })
        ]
      ```
      :::note
    
        - [JSONata](http://docs.jsonata.org/overview.html) is the query language used for the product template. JSONata provides JSON Path style queries and adds support for more advanced queries and even transformations.
        - Do not remove or modify the `parent_product_id`.

      :::

    - **Order Template**

      This template is used to create and/or update order attributes in Yotpo.
    
    - **Customer Template**

      This template is used to create and/or update customer information in Yotpo. You can add any of the supported customer attributes in the template. For example, you can include a customer contact number so when customer information is sent to Yotpo, it contains the contact number. Here is a snapshot of the default customer template.

        ```json
         {
           "customer": {
                "external_id": payload.data.id,
                "email": payload.data.email,
                "first_name": $split(payload.data.name, ' ')[0],
                "last_name": $split(payload.data.name, ' ')[1],
                "account_status": "enabled",
                "account_created_at": payload.data.meta.timestamps.created_at
              }
          }
        ```

    - **Product Rating Extension**

      The number of reviews and average ratings received for a product is saved in Commerce Manager. You must define a template to save the customer feedback. The templates follow a JSON structure, where you can mention the following information. You can use a predefined template (**Configurations** > **Templates**) or use the default one. 
        - `Name` - the name of the template.
        - `Description` - the template description.
        - `slug` - the slug to identify the template
        - `Enabled` - `true` if the template is enabled, `false` if not.
      
      Here is an example of the default template:
    
        ```json
         {
            "name": "Ratings and Reviews",
            "description": "Ratings and Reviews",
            "slug": "products(ratings)",
            "enabled": true
         }
        ```
      The Yotpo integration creates the following attributes in the product templates:
        - `review_count`
        - `average_rating` 

      View the review count and average ratings received for a product in Commerce Manager.
        
      1. Go to **Product Experience Manager** > **Products**.
      2. Click a specific product.
      3. Select **Product Templates** > **Ratings and Reviews**.

13. Click **Finish**. The integration is complete and webhooks are created for the events that you have specified.

:::note
- To see the webhooks that you have configured in Commerce Manager, click **SYSTEM** > **Store Settings** > **Webhooks**. Click each webhook to see the specific events that you have added for products, orders, and customers.
- To see the flows that you have configured for Yotpo integration in Commerce Manager, click **SYSTEM** > **Flows** > **Ratings and Reviews**.
:::

## Demo

Watch the following video to learn how to integrate Commerce with Yotpo using the **Integrations Hub** in Commerce Manager:

<iframe width="560" height="315" src="https://www.youtube.com/embed/QGK5oF5Llv4" title="Integrating with Yotpo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Integrating with Talon One

You can integrate Commerce with Talon One in Commerce Manager. Talon One is a promotion management engine that allows you to manage your promotions, referral, and loyalty strategies. This integration allows you to use Commerce catalog data in your Talon One promotions.

The integration supports the following features:

- catalog changes in Commerce changes product data in Talon One. 
- customer changes in Commerce changes customer data in Talon One.

## Talon One Integration Templates

The Talon One Integration uses product and customer request templates that contain all the parameters required for the Talon One Integration to function correctly. The Talon One Integration provides default templates. However, when configuring the integration, you can edit the product and customer templates using [JSONata](http://docs.jsonata.org/overview.html). For example, you can transform the product data from a catalog synchronization into the Talon One format, adding any data you require. Once updated and saved, the integration reviews the attributes provided in the templates and adds any that are not currently present in Talon One.

## Collecting Your Integration Setup Information

Before you configure the integration in Commerce Manager, you need to collect the necessary setup information from Talon One and Commerce Manager.

### Collecting Talon One Setup Information

You can find this information on the Recharge Dashboard in **Apps** > **API tokens**.

| Option | Description |
| --- | --- |
| **API Key** | The Talon One API key you created for this integration. |
| **API Base URL** | Your Base URL for Talon One. For example, `https://yourbaseurl.talon.one/`. |
| **Talon One Admin User Email** | The email address you used for your Talon One Admin User. |
| **Talon One Admin User Password** | The password you used for your Talon One Admin User. |
| **Talon One Catalog ID** | The ID of the Talon One catalog that you want to synchronize your Commerce data with. |

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. When you log in to Commerce Manager as a Seller Admin, you can find this information in **SYSTEM** > **Application Keys** in Commerce Manager.

| Commerce API Key | Description                                     |
|:------------------------------------|:------------------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL.  |
| **Client ID**                       | Your Commerce Client ID.     |
| **Client Secret**                   | Your Commerce Client Secret. |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Configuring Integration

1. In Commerce Manager, go to **COMPOSER > Integrations Hub**.
1. Under **Promotions**, click **Talon One**. 
1. Click **Configure**. The integration guides you through the steps you need to follow.
1. Click **Next**. The **Connections** page is displayed.
1. Enter the following details in **Commerce Connection**:

    | Name              | Description                                                                                                                                                                                                                         | 
    |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Client ID**     | Your Commerce Client ID.                                                                                                                                                                                                            |
    | **Client Secret** | Your Commerce Client Secret                                                                                                                                                                                                         |
    | **Token URL**     | Your Commerce API Token URL. For example, `https://euwest.api.elasticpath.com` (EU) or `https://useast.api.elasticpath.com` (US). See [Regions and URLs](/guides/Getting-Started/elastic-path-domains#regions-and-urls). |

1. Click **Connect**. The authorization is successfully completed.
1. Enter the following details for Talon One:

   | Option | Description |
   | --- | --- |
   | **API Key** | The Talon One API key you created for this integration. |
   | **API Base URL** | Your Base URL for Talon One. For example, `https://yourbaseurl.talon.one/`. |
   | **Talon One Admin User Email** | The email address you used for your Talon One Admin User. |
   | **Talon One Admin User Password** | The password you used for your Talon One Admin User. |
   | **Talon One Catalog ID** | The ID of the Talon One catalog that you want to synchronize your Commerce data with. |

1. Click **Next**. The **Configurations** pane is displayed.
1. Click **Store Configuration Rules**. The **Store Configuration Rules** are automatically configured to allow the integration access to flows, so no further action is required.
1. Click **Next**. The **Templates** pane is displayed. See [Talon One Integration Templates](#talon-one-integration-templates).
1. Click **Finish**. Your integration is enabled.

    In Commerce, when:

    - a catalog is published 
    - customer data is updated or added  
   
   The integration is run and the data updated in Talon One.

---

## Integrating with Advanced Commerce (GrapheneHC)

You can integrate Commerce with Advanced Commerce (GrapheneHC) using the **Integrations Hub** in Commerce Manager. This means you can synchronize Commerce data such as products, prices, images, categories, custom attributes, and variations with your Advanced Commerce (GrapheneHC) storefront, giving you advanced searching and merchandising capabilities.

The following diagram shows how Elastic Path data is sent to an Advanced Commerce (GrapheneHC) storefront. 

![Advanced Commerce (GrapheneHC Integration) diagram](/assets/ac-integration.png)

When a catalog is published, the integration automatically sends the data from Commerce to an Advanced Commerce (GrapheneHC) storefront.

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/CbF9J7Gq6AI" title="Integrating with Advanced Commerce (GrapheneHC)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Advanced Commerce (GrapheneHC) Integration Templates

The Advanced Commerce (GrapheneHC) Integration uses templates to create the data from your Commerce store in your Advanced Commerce (GrapheneHC) storefront. The templates use [JSONata](http://docs.jsonata.org/overview.html) as their query language. 

### Product Template

The Product Template creates/updates products in Advanced Commerce (GrapheneHC), including any configured locales. You can edit the template, depending on your requirements. The Product Template must conform to the Advanced Commerce [products](https://graphenehc-developer-portal.advancedcommerce.io/docs/data/schemas/products) schema.

Prices are created/updated in all currencies, in addition to any sale prices you have configured for your products.

If you have multiple currencies, in `prices`, you must provide the catalog ID for each currency you created in Advanced Commerce (GrapheneHC). For example:

`$key & "_" & $uppercase($product.meta.catalog_id)`

See [Prerequisites](#prerequisites).

If you only have one currency, you can remove this and the catalog defaults to the language configured in the Product Template.  

In `features`, you can configure the product attributes you want to display in your Advanced Commerce (GrapheneHC) storefront. The following example fetches `product_weight` and `product_height` from the `products(dimensions)` template.

```json
"features": [
    {
        "hierarchy": [
            "weight", 
            $number($product.attributes.extensions.$.'products(dimensions)'.$.'product-weight')
        ]
    },
    {
        "hierarchy": [
            "height", 
            $number($product.attributes.extensions.$.'products(dimensions)'.$.'product-height')
        ]
    }
] ~> $filter(function($v, $i, $a) {
    $count($v.hierarchy) > 1
})
```

### Category Template

The Category template creates/updates your hierarchies, nodes, and products associated with those nodes (including any configured locales) in Advanced Commerce (GrapheneHC). You can edit this template, depending on your requirements.

The Category template must conform to the Advanced Commerce [categories](https://graphenehc-developer-portal.advancedcommerce.io/docs/data/schemas/categories) schema.

### Definition Template

The Definition template creates/updates Product Experience Manager variations and options in Advanced Commerce (GrapheneHC). You can edit the template, depending on your requirements. The Definitions template must conform to the Advanced Commerce [definition](https://graphenehc-developer-portal.advancedcommerce.io/docs/data/flows/batch/files/definitions) schema.

## Collecting Your Setup Information

Before you begin configuring your integration in Commerce Manager, you need to collect the necessary setup information from Advanced Commerce (GrapheneHC) and Commerce Manager.

### Collecting Advanced Commerce (GrapheneHC) Setup Information

Collect the following setup information from Advanced Commerce (GrapheneHC).

| Option            | Description                                   |
|:------------------|:----------------------------------------------|
| **API Base URL**  | Your Advanced Commerce API Base URL, for example, `https//{{domainKey}}.api-{{location}}.advancedcommerce.services`. Contact your Advanced Commerce team. |
| **API Key** | Your Advanced Commerce API Key.  |
| **API Secret** | Your Advanced Commerce Secret.  |

### Collecting Commerce Manager Setup Information

To create a new [application key](/docs/commerce-manager/application-keys/application-keys-cm), go to **SYSTEM** > **Application Keys**.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **Token URL**                    | Your Commerce API Token URL. For example, `https://useast.api.elasticpath.com/oauth/access_token`. See [Regions and URLs](/guides/Getting-Started/elastic-path-domains#regions-and-urls).  |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Prerequisites

 - Ensure that you have [collected your setup Information](#collecting-your-setup-information).
 - In Commerce Manager, ensure that you have created the data that you want to synchronize with Advanced Commerce (GrapheneHC).
     - [products](/docs/commerce-manager/product-experience-manager/products/create-products).
     - [images](/docs/commerce-manager/product-experience-manager/products/manage-product-media).
     - [price book](/docs/commerce-manager/product-experience-manager/pricebooks/pxm-pricebooks#creating-price-books).
     - [hierarchies](/docs/commerce-manager/product-experience-manager/hierarchies/creating_hierarchies).
     - [templates](/docs/commerce-manager/product-experience-manager/extending-products/templates#creating-templates).
     - [variations](/docs/commerce-manager/product-experience-manager/variations/assign-variations-build-child-products).
     - [catalogs](/docs/commerce-manager/product-experience-manager/catalogs/creating-catalogs).

- In Advanced Commerce (GrapheneHC), ensure that you have created the following:
    - The currencies available for the products in your Commerce store catalog. Create the currencies using your Commerce catalog ID. When the catalog ID is passed in the Product Template, Advanced Commerce (GrapheneHC) displays the prices in the currencies you have configured for your catalog.
    - An Advanced Commerce (GrapheneHC) storefront for each Commerce catalog you want to publish. As part of the integration, you need to map your catalog to your Advanced Commerce (GrapheneHC) storefront ID. See [Configuring the Integration](#configuring-the-integration).
    - The languages available for the products in your Commerce catalog.

## Configuring the Integration

Now that you've met the [prerequisites](#prerequisites), let's begin with configuring the integration.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Search Integrations**, click **Advanced Commerce (GrapheneHC)** Integration.
1. Click **Configure**. The Advanced Commerce (GrapheneHC) integration guides you through the steps you need to follow to complete the integration. 
1. Click **Next**. The **Connection** page is displayed.
1. On the **Connection** page, do the following:
    1. Complete the **Commerce Connection** credential details:
        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.
        - **Token URL** - Your Commerce API Token URL
    1. Click **Connect**. The authorization is successfully completed.
    1. Complete the **Advanced Commerce (GrapheneHC) Connection** credentials:
        - **API Base URL** - Your Advanced Commerce (GrapheneHC) API base URL.
        - **API Key** - Your Advanced Commerce (GrapheneHC) API key.
        - **API Secret**  - Your Advanced Commerce (GrapheneHC) secret.
1. Click **Edit** for each template you want to edit. (#advanced-commerce-graphenehc-integration-templates).
1. Click **Next**. The **Catalog And Storefront Mapping** page is displayed.
1. From **Elastic Path Catalog** list, select the catalog you want to display in Advanced Commerce (GrapheneHC).
1. From **Advanced Commerce Storefront ID** type the ID of the Advanced Commerce storefront where you want to display your catalog. 
1. Click **Add to Catalog and Storefront Mapping** to add as many catalogs as you want.
1. Click **Finish**. Your integration is enabled.

## Troubleshooting the Advanced Commerce (GrapheneHC) Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

Select **Retry** to initiate an execution again.

---

## Integrating with Algolia

You can integrate Commerce with Algolia quickly and easily in Commerce Manager.

Whenever you publish a catalog, the full catalog is synced to Algolia using an index name composed of the catalog name and the first part of the catalog ID. This is triggered using events delivered by a webhook.

1. When a catalog is published, a `catalog-release.updated` event is triggered.
1. Once a `catalog-release.updated` event is received by the webhook, the integration begins to execute.
1. The integration performs the following:

    - Retrieves product and taxonomy data for the catalog.
    - Retrieves the mapping for Commerce fields to Algolia fields.
    - Builds or updates the Algolia index.

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/dKq9isxFtUI" title="Configuring Algolia in Commerce Manager" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Collecting Your Setup Information

Before you begin configuring your Algolia integration in Commerce Manager, you need to collect the necessary setup information from Algolia and Commerce Manager.

:::caution
Collect the following information and make sure you have it available, for example, in a text file, before configuring your Algolia integration in Commerce Manager. If you leave the Algolia Integration page in Commerce Manager, the integration is not saved and you must remove the integration and create a new one.
:::

### Collecting Algolia Setup Information

You can find this information in the **Settings, Teams and Access, API keys** section on the Algolia Dashboard.

| Option            | Description                                   |
|:------------------|:----------------------------------------------|
| **App ID**        | Your Application ID for your Algolia account. |
| **Admin API key** | Your Admin API Key for your Algolia account.  |

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key  | Description                  |
|:------------------|:-----------------------------|
| **API Base URL**  | Your Commerce API Base URL.  |
| **Client ID**     | Your Commerce Client ID.     |
| **Client Secret** | Your Commerce Client Secret. |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Configuring the Integration

Now that you've collected the setup information, let's begin by configuring the integration.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Search**, click on the **Algolia Full /Delta / Large Catalog** integration.
1. Review the **Summary** page and click **Configure**. The current version information is displayed.
1. Click **Next**.
1. Configure the following information and click **Finish**.

| Configuration parameter                                            | Value                                                                                                                                                                                                                                                                      |
|:-------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Algolia Configuration Data: algolia_app_id**                     | Your Application ID for your Algolia account.                                                                                                                                                                                                                              |
| **Algolia Configuration Data: algolia_admin_api_key**              | Your Admin API Key for your Algolia account.                                                                                                                                                                                                                               |
| **Commerce Configuration Data: Client ID**                         | Your Commerce API Client ID.                                                                                                                                                                                                                                               |
| **Commerce Configuration Data: Client Secret**                     | Your Commerce Client Secret.                                                                                                                                                                                                                                               |
| **Commerce Configuration Data: Token URL**                         | Your Commerce API Token URL. For example, `https://euwest.api.elasticpath.com//oauth/access_token` (EU) or `https://useast.api.elasticpath.com/oauth/access_token` (US). See [Regions and URLs](/guides/Getting-Started/elastic-path-domains#regions-and-urls). |
| **epcc_base_url**                                                  | Your Commerce API Base URL. For example, `https://euwest.api.elasticpath.com` (EU) or `https://useast.api.elasticpath.com` (US).                                                                                                                                           |
| **webhook_key**                                                    | Send to create secret for EPCC Integration (Examples: Simple Phrase, UUID).                                                                                                                                                                                                |
| **Post Processing Configuration Data (Optional): webhook_url**     | Optional post-processing URL that the release details are sent to upon completion of an integration attempt.                                                                                                                                                               |
| **Post Processing Configuration Data (Optional): webhook_api_key** | Optional post-processing API key for the above URL.                                                                                                                                                                                                                        |
| **Integration Tuning Parameters: batch_size**                      | The default page size when synchronizing. The default is 250.                                                                                                                                                                                                              |
| **Integration Tuning Parameters: concurrent threads**              | The number of threads that process each batch. The default is 10.                                                                                                                                                                                                          |

:::note
We recommend that you do not change the default tuning parameters. Contact Customer Success for more information.
:::

The integration starts an execution which:

- Configures a webhook to listen to the `catalog-release.updated` event, named **EPCC Algolia Integration**.
- Creates a flow for containing field mappings between Commerce and Algolia, called **Algolia Mapping**.

:::caution
You must not delete the **Algolia Mapping** flow or the **EPCC Algolia Integration** webhook, or the integration ceases to work.
:::

Now that you've configured the integration, let's learn how you use it.

## Understanding Field Mappings Between Commerce and Algolia

To sync the catalog to Algolia, you create a map of the data to pass from Commerce to Algolia. The mapping consists of:

- Source field.
- Destination field.
- Any flags to trigger optional functions.

The integration uses a flow to contain the fields that you want to use. The source of the Commerce data is the [catalog delta file](/docs/api/pxm/catalog/publish-release).
 Additionally, there are some special fields that perform additional transformation work. When the integration is initially configured, a default set of mapping fields are created. However, you can change these depending on your requirements.

The following table describes some example fields in Commerce Manager and their corresponding fields in Algolia.

| Commerce Field             | Maps to Algolia Field                                                                                                                    | Flags            |
|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------|:-----------------|
| **attributes.sales**       | ep_sales                                                                                                                                 |                  |
| **attributes.price**       | ep_price                                                                                                                                 | forceSaleFlag    |
| **attributes.description** | ep_description                                                                                                                           |                  |
| **attributes.mpn**         | ep_mpn                                                                                                                                   |                  |
| **attributes.name**        | ep_name                                                                                                                                  |                  |
| **attributes.sku**         | ep_sku                                                                                                                                   |                  |
| **attributes.slug**        | ep_slug                                                                                                                                  |                  |
| **attributes.status**      | ep_status                                                                                                                                |                  |
| **upc**                    | ep_upc                                                                                                                                   |                  |
| **main_image**             | ep_main_image_url                                                                                                                        | includeHierarchy |
| **taxonomy**               | ep_categories. This field is used to trigger the creation of a hierarchy in Algolia.                                                     |                  |

The following are special field names:

- `main_image` triggers a lookup of the URL from the file associated to the main image relationship on the product.
- `taxonomy` retrieves the hierarchy and builds a custom Algolia-friendly format.

### Alternate Taxonomy Fields

In addition to the `ep_categories` attribute, you can use the `ep_slug_categories` attribute. This attribute contains the formatted hierarchy values, but uses the **category-node slug** rather than the **category-node name**.

For example, the `ep_categories` field appears as follows

```json
{
   lvl0: "Animal & Pet Supplies"
   lvl1: "Animal & Pet Supplies > Dog"
   lvl2: "Animal & Pet Supplies > Dog > Dog Containment"
   lvl3: "Animal & Pet Supplies > Dog > Dog Containment > Dog Houses Kennels & Pens"
}
```

And the `ep_slug_categories` field appears as follows:

```json
{
   lvl0: "animal-and-pet-supplies"
   lvl1: "animal-and-pet-supplies > dog"
   lvl2: "animal-and-pet-supplies > dog > dog-containment"
   lvl3: "animal-and-pet-supplies > dog > dog-containment > dog-houses-kennels-and-pens"
}
```

Optionally, you can also generate a new field called `ep_name_plus_slug_categories` which is a formatted representation or the **category-node name**, and **category-node slug** fields  available for faceting.

Using **Create Category Name Slug Attribute**, you can enable the creation and maintenance of this field.

Set **Create Category Name Slug Attribute** to `true` if you want to create the `ep_name_plus_slug_categories` attribute field. 

For example, when enabled, the `ep_name_plus_slug_categories` field appears as follows:

```json
{
  lvl0: "Animal & Pet Supplies#animal-and-pet-supplies"
  lvl1: "Animal & Pet Supplies#animal-and-pet-supplies > Dog#dog"
  lvl2: "Animal & Pet Supplies#animal-and-pet-supplies > Dog#dog > Dog Containment#dog-containment"
  lvl3: "Animal & Pet Supplies#animal-and-pet-supplies > Dog#dog > Dog Containment#dog-containment > Dog Houses Kennels & Pens#dog-houses-kennels-and-pens"
}
```

where, for each value the Name and SLUG values are concatenated to permit them both to be available to the front-end.

In all cases, when there are multiple product->node assignments, a comma is used to separate the data in the `ep_categories`, `ep_slug_categories` and the optional `ep_name_plus_slug_categories` fields.

For example, 
```json
   lvl0: "Farm and Ranch,Power Tools and Acc,Fasteners"
```
where the product is assigned to both `Farm and Ranch`, but also `Power Tools and Acc` as well as the `Fasteners` category nodes.

### Creating new field mappings

1. In Commerce Manager, go to **Flows** > **Algolia Mapping**. (If you have just configured your integration, refresh Commerce Manager to pick up the newly-added flow from the integration.)
1. Click **New Entry**.
1. Create the field mappings you desire by supplying the source field and destination field.
1. In Algolia, create the fields described above. Refer to the documentation provided with Algolia for more information.

### Mapping flags

The following mapping flags are available.

- **includeHierarchy** - Use this flag if you want the name of the hierarchy to be included in the [`bread_crumbs`](/docs/api/pxm/catalog/catalogs#understanding-how-products-and-nodes-are-associated).
- **forceSaleFlag** - By default, if a price is on sale, an `on_sale` flag is set to `true` in the price book. 
If you also want an `on_sale` flag at the root of the product, you can add this flag to the price mapping.
- **forceJSON** - It is a `boolean` value used to determine whether the input value should be parsed as JSON. 
This is useful if you want to treat an Elastic Path field as an embedded structure and not as a string.
- **convertDateToTS** - A `boolean` value used to determine whether the input value is parsed as a date. 
The date is converted into a number that represents a UNIX timestamp.
- **isNullValue** - Use this flag if you want to set the attribute value to `1` or `0` based on whether the EPCC value resolves to `NULL`. 
This is useful when Algolia filtering is used as Algolia does not support filtering on a null parameter value.

## Managing the Integration

Once the integration is configured and you have the mappings you want, the catalog is synced with Algolia with every new publish of your catalogs.

### Partial updates

If a catalog has already been published and changes are made to the catalog and the catalog is published again, this results in a partial catalog update. In other words, only the products that have been created, updated or removed from the previous catalog release are updated. These are made directly to the live index in Algolia.

### Full updates

A full catalog update can be triggered in the following scenarios.

1. The first time a catalog is published. The delta file is then used to create a temporary index. The settings, rules, and so on, from the live version are then copied onto the temporary index. Once the index is completely loaded, the temporary index is moved to the live index.
1. You can trigger a full catalog update by setting `export_full_delta` to `true` when [publishing a catalog](/docs/api/pxm/catalog/publish-release/). Here is a sample request:

```bash
curl --location -g '{{pcmUrl}}/catalogs/{{catalogId}}/releases' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data {
    "export_full_delta" : true
}
```

### Naming catalogs and indexes

Index names are created from the catalog name and a portion of the catalog id. This allows the integration to manage many catalogs at the same time. This dependency is important to consider when naming catalogs in Commerce and indexes in Algolia.

### Updating a single product in Algolia

You can update a single Commerce product in Algolia without publishing a catalog. You can do this by sending a payload directly to an Algolia index using a URL available in the Algolia Integration. Updates to a single product checks if other catalog sync operations are in progress and delay the update until the other operations are completed.

- you can add new fields. If there are new fields that do not currently exist, they are added. You must provide the full replacement value. In the example below, `ep_categories` is a complex object. To properly update the object, the full object must be provided.
- you can update the values of existing fields.

1. Go to **Composer** > **Integrations Hub**.
2. Under **Search**, click **Algolia Full /Delta / Large Catalog**.
3. From the **Summary** tab, navigate to **Trigger details** > **UpdateObject to Algolia - Direct**.
4. Expand **UpdateObject to Algolia - Direct**.
5. From **URL**, select **Copy URl to clipboard** icon.

   :::note
   The URL is unique to each deployed instance of the Algolia Integration.
   :::

6. In Postman, open `POST {{webhook-url}}` where `webhook-url` is the URL you just copied.
7. The **Body** of the request can have the following parameters:

    | Name | Required | String | Description |
    | --- | --- | --- | --- | 
    | `index_name` | Required | `string` | The name of the Algolia index that you want to update. |
    | `objectID` | Required | `string` | The product ID of the Commerce product that you want to update. |
    | `secret_key` | Required | `string` | The Commerce Client Secret that you used when you configured the Algolia Integration. |
    | `payload` | Required | `string` | The payload contains the mapped fields for the Algolia object that you want to update. The schema must match the existing Algolia object. |

    An example request is shown below:

   ```json
   {
     "index_name": "Main_123450",
     "objectID": "b8e9af84-69f9-472c-ad18-57557e1d2c75",
     "secret_key": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=",
     "payload": {
       "ep_name": "WALL MOUNTING BRACKET",
       "ep_slug": "18-025-999",
       "ep_categories": {
       "lvl0": "Shop"
       }
     }
   }
   ```

## Filtering Catalogs

By default, every catalog publish event triggers a sync to Algolia. You can restrict this to a specific subset of catalogs using the **Selected Catalogs** filter on the **Advanced** config page.

### Configuration

| Config Variable    | Type     | Required | Description                                                                                                                                      |
|:-------------------|:---------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------------------|
| **Selected Catalogs** | list  | Yes      | Checkbox list of all available EPCC catalogs. Only catalogs checked here trigger an Algolia sync. At least one catalog must be selected. All catalogs are selected by default when installing the integration. |

### Behavior

The filter runs in the **Main Process Flow**, before any downstream sync is triggered.

| Scenario | Result |
|:---------|:-------|
| Catalog is in the selected list | Processing continues normally |
| Catalog is not in the selected list | Logged as info; execution ends silently without error |

## Filtering Products

You can control which individual products from a catalog are sent to Algolia using a JavaScript filter expression. This is useful when a catalog contains products that should not be indexed, such as child product variants.

### Configuration

Two config variables on the **Advanced** config page work together:

| Config Variable | Type | Required | Description |
|:----------------|:-----|:---------|:------------|
| **Enable Product Filtering** | boolean | No (default: `false`) | Master toggle. When `false`, all products are published and the expression below is ignored. |
| **Filter Expression** | code | No (default: `!record.attributes.base_product_id`) | A single JavaScript boolean expression evaluated against each product record. Records returning `true` are included; records returning `false` are dropped. Only evaluated when the toggle is `on`. |

:::note
The default expression `!record.attributes.base_product_id` only takes effect once **Enable Product Filtering** is turned on. Existing deployments default the toggle to `false`, so upgrade behavior is unchanged.
:::

### Filter Expression Syntax

The variable `record` refers to the current product record from the catalog JSONL file. The expression must be a **single expression** — not a function body or a multi-statement block.

Key fields available on `record`:

```
record.id                          Top-level product UUID
record.type                        Always "product"
record.attributes.status           "live" or "draft"
record.attributes.base_product     Boolean; true for base/standalone products
record.attributes.base_product_id  Empty string for parent/base products; UUID for child products
record.meta.product_types          Array, e.g. ["parent"] or ["child"]
record.attributes.extensions       Object; may contain custom extension fields
```

**Examples:**

```javascript
// Exclude child products — base_product_id is empty for parent/base, UUID for children
!record.attributes?.base_product_id
```

```javascript
// Keep only non-child products using the product_types array
!record.meta?.product_types?.includes("child")
```

```javascript
// Exclude wrapper products identified by a custom extension field
record.attributes?.extensions?.["products(metadata)"]?.["is-wrapper-product"] !== true
```

```javascript
// Combine: keep non-child products that are not wrappers
!record.meta?.product_types?.includes("child")
  && record.attributes?.extensions?.["products(metadata)"]?.["is-wrapper-product"] !== true
```

:::tip
Always use optional chaining (`?.`) when accessing nested fields to avoid per-record runtime errors. Use bracket notation for field names containing hyphens or parentheses: `record.attributes?.["field-name"]`.
:::

### Behavior and Edge Cases

| Scenario | Result |
|:---------|:-------|
| Toggle off | All products are published; expression is ignored |
| Toggle on, valid expression | Expression evaluated per record; non-matching records are silently dropped |
| Toggle on, empty expression | All records pass through; an INFO log is written |
| Expression syntax error | Step fails immediately before any records are processed; Algolia is unchanged |
| All records filtered out (full publish) | Algolia index promotion is skipped; live index is preserved; execution completes without error |
| All records filtered out (delta publish) | No writes to Algolia; live index is unchanged; execution completes without error |

### Post-Processing Webhook Payload

When a post-processing webhook URL is configured, the payload is enriched with a `filterStats` object. This is additive — all existing fields remain at the same paths.

```json
{
  "filterStats": {
    "totalBatchesSent": 12,
    "totalSuccessfulBatchCount": 12,
    "totalRetries": 0,
    "totalFilteredCount": 847,
    "totalEvalErrorCount": 0,
    "filterApplied": true
  }
}
```

When no filter is configured, `filterStats` is still present with all counters set to `0` and `filterApplied: false`.

## Using an Extension Endpoint

The integration supports an optional extension endpoint that intercepts each batch of mapped product data **after** the Commerce-to-Algolia field mapping has been applied and **before** the batch is sent to Algolia. This allows an external service to enrich, filter, or modify records in-flight.

The endpoint receives already-mapped Algolia records — it does not have access to raw Commerce attributes that were not included in the field mapping.

### Configuration

Four config variables are available on the **Advanced** config page:

| Config Variable | Type | Required | Description |
|:----------------|:-----|:---------|:------------|
| **Send Data to Extension Endpoint** | boolean | No (default: `false`) | Master toggle. When `true`, each batch is sent to the extension endpoint before Algolia. |
| **Extension Endpoint Url** | string | Yes (when enabled) | The HTTP(S) URL of the extension endpoint. |
| **Extension Endpoint Header Name** | string | No | Custom header name for authentication, for example `X-API-Key`. |
| **Extension Endpoint Header Value** | string | No | Custom header value for authentication. |

### Data Contract

The endpoint receives an HTTP POST with the Algolia multi-index batch format:

```json
{
  "requests": [
    {
      "action": "updateObject",
      "indexName": "catalog_name_abc12345",
      "body": {
        "objectID": "product-uuid",
        "ep_name": "Example Product",
        "ep_sku": "SKU-001"
      }
    }
  ]
}
```

The endpoint **must** return a response with the same `{ "requests": [...] }` wrapper. The endpoint can:

- **Enrich** — modify the `body` of any request to add or update fields.
- **Filter** — remove entries from the `requests` array to prevent specific products from being indexed.
- **Pass through** — return the data unchanged.

### Error Handling

| Extension Response | Action | Log Level |
|:-------------------|:-------|:----------|
| Valid data with requests | Extension data is sent to Algolia | — |
| Call failed or timed out | Original mapped data is sent to Algolia (graceful fallback) | Warning |
| Empty `requests` array | Batch is skipped entirely; live index is unchanged | Info |

If the extension endpoint is unreachable or returns an error, the integration falls back to sending the original mapped batch directly to Algolia. This ensures an unavailable extension endpoint does not block catalog sync.

Returning an empty `requests` array is treated as an intentional filter — no fallback to original data occurs for that batch.

:::note
The extension endpoint URL must start with `http://` or `https://`. An invalid URL fails the execution before any records are sent.
:::

---

## Integrating with Constructor.io

You can quickly and easily integrate Commerce with Constructor.io using the **Integrations Hub** in Commerce Manager. This enables you to search your Commerce products using Constructor.io. 

Whenever you publish a catalog, the full catalog is synced to Constructor.io. This is triggered using events delivered by a webhook.

1. When a catalog is published, a `catalog-release.updated` event is triggered.
1. Once a `catalog-release.updated` event is received by the webhook, the integration begins to execute.
1. The integration performs the following:

    - Retrieves the mapping for Commerce fields to Constructor.io fields.
    - Syncs all products to Constructor.io.

## Collecting Your Setup Information

Before you begin configuring your Constructor.io integration in Commerce Manager, you need to collect the necessary setup information from Constructor.io and Commerce Manager.

:::caution
Collect the following information and make sure you have it available, for example, in a text file, before configuring your Constructor.io integration in Commerce Manager. If you leave the Constructor.io Integration in Commerce Manager, the integration is not saved and you must remove the integration and create a new one.
:::

### Collecting Constructor.io Setup Information

To collect setup information from Constructor.io:

1. Go to Constructor.io.
1. Select your username.
1. Select **Account**.
1. Select **API Integration**.
1. Select **Generate API Token**.

### Collecting Commerce Manager Setup Information

In Commerce, create an application key for Constructor.io.

1. Log in to Commerce Manager as a user with Seller Admin privileges.
1. Go to **SYSTEM** > **Application Keys**.
1. Select **Create New**.
1. Type a name for your application key.
1. Select **Create**.
1. Select **Dismiss** to view your application key. 
1. To configure the integration, you need to copy the following values:

    | Commerce API Key | Description                            |
    |:------------------------------------|:---------------------------------------|
    | **API Base URL**                    | Your Commerce API Base URL. |
    | **Client ID**                       | Your Commerce Client ID. |
    | **Client Secret**                   | Your Commerce Client Secret. |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

See [Creating an Application Key in Commerce Manager](/docs/commerce-manager/application-keys/application-keys-cm).

## Configuring the Integration

Now that you've collected the setup information, let's begin by configuring the integration.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Search**, click the **Constructor.io Full Catalog Sync** integration.
1. Review the **Overview** page and click **Configure**. The current version information is displayed.
1. Click **Configure**. The **Trigger details** are displayed.
1. Click **Next**.
1. Enter the setup information you collected previously.
1. Click **Finish**.

The integration starts an execution which:

- Configures a webhook to listen to the `catalog-release.updated` event, named **EPCC Constructor.io Integration**.
- Creates a flow for containing field mappings between Commerce and Constructor.io, called **Constructor.io Mapping**.

Now that you've configured the integration, let's learn how you use it.

## Understanding Field Mappings Between Commerce and Constructor.io

To sync the catalog to Constructor.io, you create a map of the data to pass from Commerce to Constructor.io.

The integration uses a flow to contain the fields that you want to pass from Commerce to Constructor.io. The flow contains:

- A default set of mapping fields. See the table below.
- Some special fields that perform additional transformation work.

    - `main_image` triggers a lookup of the URL from the file associated to the main image relationship on the product.
    - `taxonomy` retrieves the hierarchy and builds a custom Constructor.io-friendly format.

- Any other fields that you want, depending on your requirements. 

The following table describes the default fields in Commerce Manager and their corresponding fields in Constructor.io.

| Commerce Field | Maps to Constructor.io Field                                                          | 
|:----------------------------------|:------------------------------------------------------------------------------------- |
| **attributes.productId**          | ep_product                                                                          |  
| **attributes.commodity_type**     | ep_commodity_type                                                                             | 
| **attributes.description**        | ep_description                                                                       | 
| **attributes.mpn**                | ep_mpn                                                                               | 
| **attributes.name**               | ep_name                                                                              |
| **attributes.sku**                | ep_sku                                                                               |
| **attributes.slug**               | ep_slug                                                                              |
| **attributes.status**             | ep_status                                                                            |
| **upc**                           | ep_upc                                                                               |
| **main_image**                    | ep_main_image_url in Constructor.io. You can change the name in Constructor.io but if you also change the field name in Commerce Manager, the URL lookup function is not triggered. |
| **taxonomy**                      | ep_categories. This field is used to trigger the creation of a hierarchy in Constructor.io. |

### Creating new field mappings

1. In Commerce Manager, go to **SYSTEM** > **Flows** > **Constructor.io Mapping**. If you just configured your integration, refresh Commerce Manager to pick up the newly-added flow from the integration.
1. Click **New Field**.
1. Create the field mappings you desire by supplying the EPCC field and the Constructor.io field.
1. In Constructor.io, create the fields you created in the previous step. Refer to the documentation provided with [Constructor.io](https://docs.constructor.io/)  for more information.

---

## Integrating with Coveo

You can integrate Commerce with Coveo quickly and easily in Commerce Manager.

Whenever you publish a catalog, the full catalog will be synced to Coveo. This is triggered using events delivered by a webhook.

1. When a catalog is published, a `catalog-release.updated` event is triggered.
1. Once a `catalog-release.updated` event is received by the webhook, the integration begins to execute.
1. The integration performs the following:
    - Builds a taxonomy for the catalog.
    - Retrieves the mapping for Commerce fields to Coveo fields.
    - Adds any missing fields to Coveo.
    - Delete Coveo contents.
    - Sync all products to Coveo.

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/pqtwtFSJ8jM" title="Integrating with Coveo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Collecting Your Setup Information

Before you begin configuring your Coveo integration in Commerce Manager, you need to collect the necessary setup information from Coveo and Commerce Manager.

:::caution
Collect the following information and make sure you have it available, for example, in a text file, before configuring your Coveo integration in Commerce Manager. If you leave the Coveo Integration page in Commerce Manager, the integration is not saved and you must remove the integration and create a new one.
:::

### Collecting Coveo Setup Information

You can find this information in the Coveo Administration Console.

| Option                    | Description                                      |
|:--------------------------|:-------------------------------------------------|
| **Coveo Organization ID** | The key given to your organization. You can find this by clicking **Organization** > **Settings** and selecting the **Organization** tab. |
| **Source ID**             | The URL of your Coveo source. You can find this by clicking **Content** > **Sources**, selecting your source, and clicking **Edit**. |
| **Coveo Source API key**  | The key you stored when you created your source. |
| **Coveo Fields API key**  | The key you created that has access to create fields. |
| **Coveo Site URL**        | The base URL to be prefixed to the product URL. For example, if your products URL is `https://your.domain.com/products/:slug` then your base URl is `https://your.domain.com/products/`. |

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key                            | Description |
|:---------------------------------------------------------------|:------------|
| **Commerce Base URL**                       | Your Commerce base URL. |
| **Commerce Client ID**                      | Your Commerce Client ID. |
| **Commerce Client Secret**                  | Your Commerce Client Secret. |
| **Commerce Integration Webhook Secret Key** | This can be anything you choose. |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Configuring the Integration

Now that you've collected the setup information, let's begin by configuring the integration.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Search**, click on the **Coveo Full Catalog Sync** Integration.
1. Click **Configure**. The **Trigger details** are displayed.
1, Click **Next**.
1. Enter the setup information you collected previously.
1. Click **Finish**.

The integration starts an execution which:

- Configures a webhook to listen to the `catalog-release.updated` event, named **EPCC Coveo Integration**.
- Creates a flow for containing field mappings between Commerce and Algolia, called **Coveo Mapping**.

:::caution
It is important that you don't delete the **Coveo Mapping** flow or the **EPCC Coveo Integration** webhook, or the integration ceases to work.
:::

Now that you've configured the integration, let's learn how you use it.

## Understanding Field Mappings Between Commerce and Coveo

To sync the catalog to Coveo you must map the data to pass from Commerce to Coveo.

The integration uses a flow to contain the fields that you want to pass from Commerce to Coveo. These can be any fields you like. There are some special fields and a default set which are created when you first configure the integration. See the table below.

Coveo fields must have:

- A field type of either LONG, LONG_64, DOUBLE, DATE or STRING.
- Coveo schema details such as a JSON object containing any additional data needed.
- Coveo Facet is either TRUE or FALSE, depending on if the Coveo field is used as facet or not.
- Coveo Multifacet is either TRUE or FALSE, depending on if the Coveo field is used as a facet with multiple values or not.
- Multifacet tokenizer if the Coveo field is a multivalued facet where character delimits the values.

The following table describes some example fields in Commerce Manager and their corresponding fields in Coveo.

| Commerce Field | Maps to Coveo Field                      |
|:----------------------------------|:-----------------------------------------|
| **attributes.productId**           | ep_product                               |
| **attributes.commodity_type**         | ep_commodity_type                        |
| **attributes.description**        | ep_description                           |
| **attributes.mpn**                | ep_mpn                                   |
| **attributes.name**               | ep_description                           |
| **attributes.sku**                | ep_sku                                   |
| **attributes.slug**               | ep_slug                                  |
| **attributes.status**             | ep_status                                |
| **upc**                           | ep_upc                                   |
| **main_image**                    | `ep_main_image_url` in Coveo. You can change the name in Coveo but if you also change the field name in Commerce Manager, the URL lookup function is not triggered. |
| **taxonomy**                      | ep_categories. This field is used to trigger the creation of a hierarchy in Coveo. |

### Creating New Field Mappings

1. In Commerce Manager, go to the **Coveo Mapping** page under the Flows. (If you just configured your integration, refresh your Commerce Manager tab to pick up the newly added flow from the integration.)
1. Click **New Entry**.
1. Create the field mappings you desire by supplying the EPCC Field, the Coveo Field, the Coveo Field Type, and the additional Coveo details in the entry.
1. In Coveo, create the fields described above. Refer to the documentation provided with Coveo for more information.

---

## Integrating with Elasticsearch

You can integrate Commerce with Elasticsearch quickly and easily in Commerce Manager.

Whenever you publish a catalog, the full catalog will be synced to Elasticsearch. This is triggered using events delivered by a webhook.

1. When a catalog is published, a `catalog-release.updated` event is triggered.
1. Once a `catalog-release.updated` event is received by the webhook, the integration begins to execute.
1. The integration performs the following:
    - Builds a taxonomy for the catalog.
    - Retrieves the mapping for Commerce fields to Elasticsearch fields.
    - Syncs all products to Elasticsearch.

## Elasticsearch Prerequisites

You must create an index called `search-products` in your Elasticsearch instance before configuring the integration in Commerce.

You must create the index using a `join` data type. The `join` data type is a special field that creates parent/child relations within documents of the same index. The `relations` section defines a set of possible relations within the documents, each relation being a parent name and a child name. See https://www.elastic.co/guide/en/elasticsearch/reference/8.6/parent-join.html for more information.

```json
{
    "mappings": {
        "properties": {
            "my_join_field": {
                "type": "join",
                "relations": {
                    "parentID": "childID"
                }
            }
        }
    }
}
```

## Collecting Your Setup Information

Before you begin configuring your Elasticsearch integration in Commerce Manager, you need to collect the necessary setup information from Elasticsearch and Commerce Manager.

:::caution
Collect the following information and make sure you have it available, for example, in a text file, before configuring your Elasticsearch integration in Commerce Manager. If you leave the Elasticsearch Integration page in Commerce Manager, the integration is not saved and you must remove the integration and create a new one.
:::

### Collecting Elasticsearch Setup Information

You can find this information in the **Management** section on the Elasticsearch Dashboard.

| Option                | Description                                            |
|:----------------------|:-------------------------------------------------------|
| **Admin API Token**   | Your Admin API Key for your Elasticsearch account.     |
| **Indexing Endpoint** | Your Indexing Endpoint for your Elasticsearch account. |
| **Elasticsearch Host** | Your Elastic Search URL.                       |

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. You can find this information in **System** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **API Base URL**                    | Your Commerce API Base URL. |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Configuring the Integration

Now that you've collected the setup information let's begin by configuring the integration.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Search** click on the **Elasticsearch Cloud Full Catalog Sync** Integration.
1. Click **Configure**. The **Trigger details** are displayed.
1, Click **Next**.
1. Enter the setup information you collected previously.
1. Click **Finish**.

The integration starts an execution which:

- Configures a webhook to listen to the `catalog-release.updated` event, named **EPCC Constructor.io Integration**.
- Creates a flow for containing field mappings between Commerce and Elasticsearch, called **Constructor.io Mapping**.

:::caution
It is important that you don't delete the **Constructor.io Mapping** flow or the **EPCC Constructor.io Integration** webhook, or the integration ceases to work.
:::

Now that you've configured the integration, let's learn how you use it.

## Understanding Field Mappings Between Commerce and Constructor.io

To sync the catalog to Elasticsearch you must map the data to pass from Commerce to Elasticsearch.

The integration uses a flow to contain the fields that you want to pass from Commerce to Elasticsearch. These can be any fields you like. There are some special fields and a default set which are created when you first configure the integration. See the table below.

The following table describes some example fields in Commerce Manager and their corresponding fields in Elasticsearch.

| Commerce Field | Maps to Elasticsearch Field              |
|:----------------------------------|:-----------------------------------------|
| **attributes.productId**              | ep_product                               |
| **attributes.commodity_type**        | ep_commodity_type                        |
| **attributes.description**        | ep_description                           |
| **attributes.mpn**                | ep_mpn                                   |
| **attributes.name**               | ep_description                           |
| **attributes.sku**                | ep_sku                                   |
| **attributes.slug**               | ep_slug                                  |
| **attributes.status**             | ep_status                                |
| **upc**                           | ep_upc                                   |
| **main_image**                    | `ep_main_image_url` in Elasticsearch. You can change the name in Elasticsearch but if you also change the field name in Commerce Manager, the URL lookup function is not triggered. |
| **taxonomy**                      | ep_categories. This field is used to trigger the creation of a hierarchy in Elasticsearch. |

### Creating New Field Mappings

1. In Commerce Manager, go to **SYSTEM** > **Flows** > **Elasticsearch Mapping**. If you just configured your integration, refresh Commerce Manager to pick up the newly-added flow from the integration.
1. Click **New Field**.
1. Create the field mappings you desire by supplying the EPCC field and the Elasticsearch field.
1. In Elasticsearch, create the fields you created in the previous step. Refer to the documentation provided with Elasticsearch for more information.

---

## Integrating with Klevu Catalog Sync

You can integrate Commerce with Klevu quickly and easily in Commerce Manager. Klevu is an advanced AI-driven search and product discovery platform specifically designed for e-commerce websites. Once you have integrated Klevu, you can synchronize catalog from Commerce Manager to Klevu.

## Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. You can find this information in **System** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges.

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |
| **Token URL**                       | Your Commerce API token URL. US Region: https://useast.cm.elasticpath.com/oauth/access_tokenEU Region: https://euwest.cm.elasticpath.com/oauth/access_token |

## Configuring the Integration

Now that you've collected the setup information let's begin by configuring the integration.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **Search** click on the **Klevu Catalog Sync** Integration.
1. Click **Configure**. The **Trigger details** are displayed.
1. Click **Next**. The **Connections** page is displayed.
1. Enter the **Elastic Path Commerce Cloud Connection** details. See [Collecting Commerce Manager Setup Information](#collecting-commerce-manager-setup-information).
1. Click **Connect**. A new window is displayed to confirm the connection was successful. If successful, close this window and then click **Next**.
1. By default, **Fetch Main Image URL** and **Fetch Inventory** toggles are enabled. You can modify the default configuration policy, batch size and concurrency settings if necessary. We recommend keeping these settings as default.
1. Click **Next**.
1. Provide the **Base Product URL** and **Base Category URL** relevant to your products and categories. For example, `https://www.example.com/products` and `https://www.example.com/category`.
1. Click **Finish** to complete the configuration process.

## Understanding Klevu Mappings

Once you have configured the integration, it creates:

- A Custom API named **Klevu Keys** under **COMMERCE EXTENSIONS** to map Klevu store credentials for publishing the catalog.
- A flow named **Klevu Mapping** under **SYSTEM > Flows** for mapping Klevu and custom fields. 
- A Webhook event named **Klevu Catalog Sync**.

The following table describes the Commerce product fields and their corresponding Klevu attributes:

| Commerce Product Fields                    | Maps to Klevu Attributes |
|:----------------------------------|:-----------------------------------------|
| **product.attributes.sku**           | Klevu sku |
| **product.attributes.name**          | Klevu name |
| **product.attributes.description**    | Klevu description |
| **product.attributes.prices**         |  Klevu prices |
| **product_base_url**/**product.attributes.slug** | Klevu url |
| **Main image URL**                            | Klevu images default url |
| **product.meta.child_variations[forEach].option.name** | Klevu custom attribute.  A list of all possible variations is created and verified to ensure all potential attributes exist in Klevu before initiating the catalog sync. |
| **product.attributes.base_product_id** | Klevu parent Product |
| **product.meta.breadcrumbs [flattened]** |  Klevu categories |

## Creating New Entries and Publishing Catalogs

To synchronize each catalog, you must create a separate Klevu store and collect API key and Klevu Rest Auth key. Klevu does not support multiple indexes within a single Klevu store. 

Follow these steps to input Klevu credentials into the custom API **Klevu Keys**:

1. In Commerce Manager, navigate to **COMMERCE EXTENSIONS** > **Custom APIs**.
1. Select **Klevu Keys** and click **All Entries**.
1. Select **Create Entry**.
1. Specify the name of the catalog you wish to synchronize.
1. Paste the API key that you copied from the Klevu store in the **Klevu API Key** field.
1. Enter the Klevu API key for Indexing, which is `https://indexing.ksearchnet.com`.
1. Paste the Klevu Rest Auth key that you copied from your Klevu store in the **Klevu REST AUTH Key** field.
1. In the **Source Catalog ID** field, provide the catalog ID for the catalog you want to synchronize.
1. Click **Create Entry**.
1. Once you have created a new entry, you can publish the catalog. See [Publishing Catalogs](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs#publishing-catalogs).

---

## Integrating with Amazon Cognito

You can integrate Commerce with Amazon Cognito using the **Integrations Hub** in Commerce Manager. This allows you to offer your customers or business users Single Sign-on (SSO) using Amazon Cognito credentials instead of Commerce credentials. When you create an Amazon Cognito integration, an Amazon Cognito user pool is created. Your customers can then sign-in directly using the user pool.

Commerce has two per-store, pre-set authentication realms.

- Buyer Organization. A Buyer Organization is for customers who buy products from your store.
- Merchant Organization. A Merchant Organization is for business user's who log in to Commerce Manager to modify a store's settings or catalogs.

You can enable Single Sign-on (SSO), using Amazon Cognito in a Buyer Organization realm, a Merchant Organization realm, or both.

:::note
Amazon Cognito provides the capability to federate identity from other providers like, Facebook, Google, Amazon, Apple, SAML-based and OIDC providers. This is not available as part of this integration.
:::

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/Y0mv--xczX8" title="Integrating with AWS Cognito" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Understanding Amazon Cognito Integration Request Templates

The Amazon Cognito Integration uses the following Amazon Cognito API requests to create/update user pools and user pool clients.

- [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html).
- [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html).
- [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html).
- [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html).

The Amazon Cognito Integration Request Templates contain all the parameters required for the Amazon Cognito Integration to function correctly. You can edit these templates, when configuring your Amazon Cognito Integration, to change or add any additional parameters that Amazon Cognito provide, depending on your business requirements. For example, you may want to change the password policies.

There are some parameters that you must not change. 

**Create User Pool Request Template**

```json
{ 
  "PoolName": "{{poolName}}"
}
```

**Update User Pool Request Template**

```json
{
  "UserPoolId": "{{userPoolId}}"
}
```

**Create User Pool Client Request Template**

```json
{
          "UserPoolId": "{{userPoolId}}",
          "ClientName": "{{poolName}}"
}
```

**Update User Pool Client Request Template**

 ```json
{
  "UserPoolId": "{{userPoolId}}",
  "ClientName": "{{poolName}}"
}
  "CallbackURLs": [
  {% for url in callbackUrl %}
  {% unless forloop.first %},{% endunless %}
  "{{url}}"
  {% endfor %}
  ]`
 ```

## Prerequisites

When configuring your Amazon Cognito Integration in **Integrations Hub**, you need to provide some or all of the following information, depending on your requirements.

### Configuring Amazon Cognito Prerequisites

When configuring your Amazon Cognito Integration in **Integrations Hub**, you must provide your AWS region, for example, `us-east-1`.

In addition, you may optionally want to configure the following:

- You can enable Multi-Factor Authentication (MFA).
- You can set-up Short Message Service (SMS) Settings. See [SMS message settings for Amazon Cognito user pools](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-sms-settings.html)
- You can customize a page hosted in Amazon Cognito, for example, include a logo or define CSS. See [Customizing the built-in app UI to sign up and sign in users](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-ux.html).

### Configuring Commerce Prerequisites

If you want to use Amazon Cognito with an Commerce Merchant Organization realm, configure a Merchant Organization prefix. You can configure this in Commerce Manager in **SYSTEM** > **Store Settings** > **Authentication Management**. The prefix field is available from the **Enter your store's prefix** drop-down list during login to determine the Commerce Merchant realm that your business users log in to. See [Merchant Organization: URL prefix](/docs/api/single-sign-on).

## Collecting Your Setup Information

Before you begin configuring your Amazon Cognito integration in Commerce Manager, you need to collect the necessary setup information from Amazon Cognito and Commerce Manager.

### Collecting Amazon Cognito Setup Information

Collect the following Amazon credentials. See [Create an AWS access key](https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/).

| Amazon Cognito Connection | Description                 |
|:-----------------------|:----------------------------|
| **Access Key ID**      | Your AWS Access Key ID.     |
| **Secret Access Key**  | Your AWS Secret Access Key. |

### Collecting Commerce Manager Setup Information

Collect the following Commerce API keys. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. See [Application Keys](/docs/api/application-keys/application-keys-introduction).

| Commerce API Key | Description                            |
|:------------------------------------|:---------------------------------------|
| **Token URL**                       | Your Commerce API Token URL. For example, `api.motlin.com/oauth/<access_token>` (EU) or `useast.api.elasticpath.com/oauth/<access_token>` (US). |
| **Client ID**                       | Your Commerce Client ID. |
| **Client Secret**                   | Your Commerce Client Secret. |

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Configuring the Amazon Cognito Integration

Once you have:

- [Understood the prerequisites](#prerequisites).
- [Collected your setup information](#collecting-your-setup-information).

You are ready to configure the Amazon Cognito integration in **Integrations Hub**.

1. In Commerce Manager, go to **COMPOSER** > **Integrations Hub**.
1. Under **SSO**, click **Amazon Cognito**. The **Amazon Cognito** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** consist of some details about the **Amazon Cognito** integration.
1. Click **Next**. The **Configuration** page is displayed.
1. Complete the information in the **Configuration** page.

    - **Client-ID**  - Your Commerce Client ID.
    - **Client-Secret** - Your Commerce Client Secret.
    - **Token URL** - Your Commerce API Token URL.

1. Click **Connect** to make sure that the authentication is completed successfully.
1. Complete the Amazon Cognito credentials.

    - **Access Key ID**  - Your AWS Access Key ID.
    - **Secret Access Key** - Your AWS Secret Access Key.
1. In **AWS Region**, provide your AWS region, for example, `us-east-1`.
1. In **User Pool Name**, type the name you want to use for your user pool. By default, this is **EPCC**.
1. In **User Pool Domain Name**, type the domain name you want to use for your user pool. It must be unique. We recommend that your domain name is alphanumeric and you only use the `-` special character. The domain is in the format of `https://*<domain_prefix>*.auth.<*region*>.amazoncognito.com`. For example, if your domain name is `elasticpath-commerce-cloud` and your AWS region is `us-east-1` then your login URL is `elastic-path-commerce-cloud.auth.us-east-1.amazoncognito.com`. The Amazon Cognito Integration creates a subdomain within an Amazon Cognito domain. If you want to use your business domain, then you must configure this directly in Amazon Cognito.
1. In **OIDC Profile Name**, provide the name of the Commerce OIDC profile.
1. Click **Next**. The **Buyer Organization** configuration page is displayed.
1. If you want to enable Amazon Cognito in your Buyer Organization, turn on the **Enable Buyer Organization** toggle.
1. (Optional) In **SSO Callback URL (Storefront)** you can add additional storefront callback URLs. Once your customer has successfully logged in, you want Amazon Cognito to redirect them to your storefront. You may have a different storefront for different geographical regions, for example, US and UK, but you want to use the same Amazon Cognito User Pool. In this scenario, you can give a storefront callback URL for each region. Select **Add value** to add a maximum of 5 URLs.
1. Click **Next**. The **Merchant Organization** configuration page is displayed.
1. If you want to enable Amazon Cognito in your Merchant Organization, turn on the **Enable Merchant Organization** toggle.
1. In **SSO Prefix (Merchant)**, provide your Merchant Organization prefix. The prefix field is used during login to determine the Commerce Merchant realm that your business users log in to.
1. Click **Next**. The **Templates** configuration page is displayed. You can use the default request templates provided by the Amazon Cognito Integration or you can edit them, depending on your requirements. For example,  you may want to change the password policies. Click **Edit** for the request template you want to edit. However, there are some parameters that you must not change. See [Understanding Amazon Cognito Integration Request Templates](/docs/composer/integration-hub/store-management/aws-cognito-integration).
1. Click **Finish**. Your integration is enabled.

## Using Amazon Cognito Integration

To change any configuration details in your Amazon Cognito integration, open your Amazon Cognito Integration and go to **Summary** > **Reconfigure**.

In addition, from **Summary**, you can view, pause, or delete your Amazon Cognito integration.

If there is an update to the Commerce Amazon Cognito integration, a message is displayed in **Summary**. Click **Update** to update your integration. Walk through the steps to configure your integration.

## Troubleshooting the Amazon Cognito Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

From **Step Outputs**, you can do the following.

1. Select **Integration Trigger** to see any errors when the integration was triggered.
1. Select **List User Pool** to see the details of the Amazon Cognito User Pool.

Select **Retry** to initiate an execution again.

---

## Commerce Catalog Publisher

The Commerce Catalog Publisher is a utility in the **Integrations Hub** in Commerce Manager that enables you to publish many Commerce store catalogs in one publish operation. 

An example of how the store catalogs are published using the Catalog Publisher integration is described below.

1. When triggered, the integration retrieves the store catalogs.
1. For each store catalog, the integration triggers a catalog publish operation. 
1. The integration waits for the catalog publish to complete.  
1. When the catalog publish is complete, the integration waits a specific period of time to allow for any corresponding events linked to a store catalog to complete. For example, if you are using Algolia, you may want to wait for the Algolia re-index operation to complete. 
1. The integration publishes the next catalog, if any remain.  Otherwise, the process completes.

## Using Catalog Publisher

To publish your store catalogs, you must invoke the webhook that is created when you configure the Catalog Publisher integration. You can either publish all store catalogs or supply an array of the catalog IDs that you want to publish. 

### Request Example

```json
{
  "catalogIds": ["59935562-8c44-11ed-a1eb-0242ac120002","59935846-8c44-11ed-a1eb-0242ac120002"]
}
```

## Configuring the Catalog Publisher Integration

You configure the Catalog Publisher integration in **Integrations Hub**.

1. In Commerce Manager, go to the store from which you want to publish your store catalogs.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, click **Commerce Catalog Publisher**. The **Commerce Catalog Publisher** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** are displayed.
1. Click **Next**. The **Commerce Connection** page is displayed.
1. Complete the information in the **Commerce Connection** page. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. See [Application Keys](/docs/api/application-keys/application-keys-introduction). The table below describes the options you can configure. 

    | Option | Description |
    |:--- | :--- |
    | **publish_check_delay** | The delay, in milliseconds, between status checks. Default value is 300000. |
    | **algolia_publish_delay** | The delay, in milliseconds, to wait for any corresponding events linked to your catalog to complete. For example, if you are using Algolia, you may want to wait for the Algolia re-index operation to complete. Default value is 300000. |
    | **check_status_retry** | The maximum number of times the integration checks the status and retries. Default value is 15. |
    | **publish_schedule**  | The cron schedule for a full catalog publish. Default value is `0 7 * * SUN`. |
    | **publish_concurrently**  | Turn on the **publish_concurrently** toggle to publish your catalogs concurrently. The integration supports concurrently publishing up to 20 catalogs. If more than 20 catalogs are included, the integration returns an error. If the **publish_concurrently** toggle is off, then catalogs are published sequentially one after another. There is no limit on the number of catalogs that can be published sequentially. |
    | **Client-ID** | Your Commerce Client ID. |
    | **Client-Secret** | Your Commerce Client Secret. | 
    | **Token URL** |Your Commerce API Token URL. For example, `api.motlin.com/oauth/<access_token>` (EU) or `useast.api.elasticpath.com/oauth/<access_token>` (US).|

    :::note
    When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
    :::

1. Click **Connect**.
1. Click **Next**. The **Commerce Catalogs** page is displayed. You must select catalogs to be included in the publication. 
1. Select the catalogs you want to publish. You can select:
    - **All catalogs**: All the catalogs available in your store are automatically selected.
    - **Selected catalogs**: Select the specific catalogs you want to publish and assign them a priority value (any integer between 1 and 100). Catalogs with a higher priority are published first. If a priority value is not set, the integration assigns a default priority of 100. Prioritization does not apply when catalogs are published concurrently. 
1. Click **Finish**. Your integration is enabled. You must enable a Catalog Publisher integration on each store where you want to import your product data set.  

## Using Catalog Publisher Integration

Using the Catalog Publisher, you can:

- Publish all or some of your store catalogs
- Check the publish status of your store catalogs
- Schedule your store catalog publishing

You can publish using Postman. 

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Catalog Publisher**. You must have configured a Catalog Publisher integration before you can publish any catalogs for this store. See [Configuring the Catalog Publisher Integration](##configuring-the-catalog-publisher-integration).
1. From **Summary** > **Trigger Details**. 

    - Expand **Publish Catalog Flow** if you want to publish specific catalogs.
    - Expand **Check Publish Status Flow** if you want to check the publish status of all or some of your catalogs.
    - Expand **Schedule Flow** if you want to schedule publishing your catalogs.
    - Expand **Publish Complete Flow** if you want to publish all your catalogs.

1. Select **Copy to Clipboard** to copy the URLs.
1. Go to Postman.
1. Open `POST {{webhook-url}}` where *webhook-url* is the webhook you copied in step 5.
1. You can supply the folllowing parameters in **Body**, depending on the flow you are using. 

    - **Publish Catalog Flow** - An array of catalog IDs.
   
       ```
       {
        "catalogIds": ["4f37dd4e-75c6-4f43-8888-0ea8d4963480","0776c723-971a-444b-b0e0-4967e9b9164c"]
       }
       ```

    - **Check Publish Status Flow** - An array of catalog IDs, the catalog release ID and the `statusCheckRetryCount` to specify the maximum number of times the integration checks the status and retries.
      ```
       {
        "catalogIds": ["4f37dd4e-75c6-4f43-8888-0ea8d4963480","0776c723-971a-444b-b0e0-4967e9b9164c"],
        "releaseId": "cb7f8365-3194-44df-aa1a-13ec0f279c58",
        "statusCheckRetryCount":5
       }
       ```

    - **Schedule Flow** - Leave empty to publish all catalogs.
    - **Publish Complete Flow** - An array of catalog IDs.
      ```
       {
        "catalogIds": ["4f37dd4e-75c6-4f43-8888-0ea8d4963480","0776c723-971a-444b-b0e0-4967e9b9164c"]
       }
       ```

1. Run `POST {{webhook-url}}`.
1. When the publish has finished, if you go to your store, you should see your published store catalogs.

## Troubleshooting the Catalog Publisher Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

Select **Retry** to initiate an execution again.

---

## Commerce Legacy to Product Experience Manager Catalogs Migration

The Commerce Legacy to Product Experience Manager Catalog Migration is a utility in the **Integrations Hub** of Commerce Manager. This enables you to migrate all Version 2 capabilities, for example, `Products`, `Extended Data`, `Brands`, and `Collections`to Product Experience Manager.

## What Legacy Features are Supported in Product Experience Manager?

| Legacy Features | Product Experience Manager |
| ---------------------------- |----------------------------|
| Categories and subcategories | ✅                          |
| Brands and Collections | ✅                          |
| Product custom fields | ✅                          |
| Variation, option, and option modifiers | ✅                          |

## How are Legacy Features Represented in Product Experience Manager?

| Legacy Features | Product Experience Manager |
| --- | --- | 
| Categories and subcategories | Hierarchies and nodes. For more information, see [Hierarchies](/docs/api/pxm/products/hierarchies). |
| Brands and collections | Products from a specific brand are grouped together and represented as a node in a hierarchy.Once the products and hierarchies are created in Product Experience Manager, the relationships between the nodes and products are migrated from Legacy catalogs. |
| Product custom fields | Product templates. If there are more than 100 custom fields, multiple product templates are created.The templates are titled as `Products 1`, `Products 2`, and so on.The templates are assigned to the products.For more information, see [Templates](/docs/api/flows/flows-service-introduction#templates-in-product-experience-manager). |
| Variation, options, and option modifiers | Variations. All option modifiers are currently supported with the exception of `sku_builder` and `slug_builder` modifiers. Please contact your customer service representative, if you want to add any of the modifiers to the supported list.Price modifiers are supported and migrated to the price book, replicating the same impact on product catalogs.Price modifier reference is added to the variations.Variation option modifier provides the ability to differentiate between catalogs.For more information, see [Product Variations](/docs/api/pxm/products/variations). |

## Prerequisites

You must complete the following before migrating legacy catalogs to Product Experience Manager product catalogs.

### Composable Commerce connection details

You must log in as a user with seller admin privileges.

1. In Commerce Manager, under **SYSTEM**, click **Application Keys**. 
2. Click **Create New**.
3. Click **Create**.

    The **New Application Key** page appears.

4. In the **Name** field, enter a name. For example, **Legacy Migration Tool**.
5. Click **Dismiss**.

    The **Keys** page appears.

6. Copy the following values:

    - API Base URL
    - Client ID
    - Client Secret

7. Enter a value for the **Secret Phrase**. This is required when you want to manually trigger the migration. For example, `{"secret": "This is my answer to the secret phrase."}`.

## Configuring Legacy to Product Experience Manager Migration Tool

Once you have completed the [Prerequisites](#prequisites), you are ready to configure the Legacy to Product Experience Manager Migration tool:

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Under **Store Management & Configuration**, click **Legacy to Product Experience Manager Catalog Migration**.
3. Click **Configure**.

    A window appears where you must configure the tool. In the **Name** field, the name that you have previously entered for this migration tool appears.

4. Click **Next**.
5. In the **Initial Configuration**, enter the following values that you have previously copied:

    - Client ID: This is the Commerce Client ID.
    - Client Secret: This is the Commerce Client Secret
    - Base URL: Remove the URL that is not applicable to your location.
    - Secret Phrase: This is the secret phrase that you have saved while configuring the Commerce Connection details.

6. Click **Finish**.

    You have successfully completed the steps required to start migrating the legacy catalogs to Product Experience Manager catalogs.

## Migrating Legacy Catalogs to Product Experience Manager Catalogs

The migration process is completed in three phases:

1. **Taxonomy migration**: During this phase, the products classification is migrated to Product Experience Manager.
2. **Product and product price migration**: During this phase, products along with their prices are migrated to Product Experience Manager.
3. **Categories and subcategories migration**: During this phase, products are assigned to hierarchies and nodes in Product Experience Manager. 

### Step 1: Taxonomy migration

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Click **Legacy to Product Experience Manager Catalog Migration**.
3. Click the **Test** tab.
4. In the **Flow Selector** list, select **Copy Categories to Product Experience Manager**.
5. In the **Payload body**, add a JSON object consisting of 1 key value pair `{"secret": "your secret phrase."}`.
6. Copy the JSON object as you require this later.
7. Click **Save & Run Test**.

![Legacy Catalogs to Product Experience Manager Catalogs Migration](/assets/legacy-catalogs-pxm-catalogs-migration.png)

    In the **Logs** tab, you can check the progress of this migration. When the **Message** column for this migration is updated to **Ending Instance Legacy to PxM Catalog Migration - Copy Categories to Product Experience Manager**, the taxonomy migration process is complete.

### Step 2: Products and prices migration

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Click **Legacy to Product Experience Manager Catalog Migration**.
3. Click the **Test** tab.
4. In the **Flow Selector** list, select **Copy Products and Prices to Product Experience Manager**.
5. In the **Payload body**, paste the JSON object that you previously copied while migrating the taxonomy.
6. Click **Save & Run Test**.

    In the **Logs** tab, you can check the progress of this migration. When the **Message** column for this migration is updated to **Ending Instance Legacy to PXM Catalog Migration - Copy Products and Prices to Product Experience Manager**, this migration is complete.

### Step 3: Assignment of products to nodes migration

1. In Commerce Manager, under **COMPOSER**, click **Integrations Hub**.
2. Click **Legacy to Product Experience Manager Catalog Migration**.
3. Click the **Test** tab.
4. In the **Flow Selector** list, select **Assign Products to Nodes**.
5. In the **Payload body**, paste the JSON object that you previously copied while migrating the taxonomy.
6. Click **Save & Run Test**.

   The products are assigned to hierarchies and nodes. Hierarchies and nodes in Product Experience Manager function similarly to brands and collections in Version 2.

## Creating and Publishing Product Experience Manager Product Catalog with Legacy Products

After the migration is complete, you can create a Product Experience Manager product catalog with price book and hierarchies.
Perform the following steps:

1. In Commerce Manager, under **PRODUCT EXPERIENCE MANAGER**, click **Catalogs**.

    The **Catalogs** page appears.

2. Click **Add Catalog**.

    The **Catalog: Add Catalog** page appears.

3. In the **Name** field, enter a name for the catalog.
4. (Optional) In the **Description** field, enter a description for the catalog.
5. In the **Hierarchy** field, select the hierarchies you want to add to the catalog. You can add more than one hierarchy to a catalog.
6. In **Price Books**, select a price book.
7. Click **Save**.
8. Under **PRODUCT EXPERIENCE MANAGER**, click **Catalogs**.

    The catalog that you have just created is listed on this page.

9. Double-click the catalog and then click **Publish**.

   Or,  
   
   Click [Three dots](/assets/three-dots.png) next to the catalog and then click **Publish**.

## Demos

<iframe width="560" height="315" src="https://www.youtube.com/embed/y3rEhfSElsw" title="Integrations Hub - Legacy to Product Experience Manager Migration" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Commerce Inventory Import

The Commerce Inventory Import is a utility in the **Integrations Hub** in Commerce Manager that enables you to quickly and easily create and update inventory data in your Commerce store. Using the Commerce Inventory Import utility, you can:

- Create inventory when an inventory object does not exist for a product.
- Update inventory values based on the strategy you select when an inventory object exists for a product.

You can perform the following actions:

- Decrement stock.
- Increment stock.
- Match available stock. The Inventory Import Utility reads the existing stock available value, calculates the adjustment then increments or decrements the stock value.

Products are identified by either:

- `SKU` - The unique stock keeping unit of the product.
- `external_ref` -  The unique attribute associated with the product.

An example of how inventory data is imported using an Inventory Import integration is described below.

1. Create a JSON file with the inventory data you want to import. You can have more than one JSON file, depending on your requirements. See [Inventory Import Integration File Format](#inventory-import-integration-file-format).
1. Configure an Inventory Import integration in the store where you want to import the inventory data. This creates the webhooks that consumes the message and JSON files when you send the API request to import the inventory data.
1. In Postman, run `POST {{webhook-url}}` request. As part of the request, you must supply the Gzip file URLs for the JSON files you want to process as part of the import. See [Using Inventory Import Integration Files](#using-inventory-import-integration-files).

    - The Inventory Import integration processes your Gzip files.
    - The inventory data are imported to the store.

## Inventory Import Integration File Format

The data that you provide to the Inventory Import integration must conform to [JSON Lines](https://jsonlines.org/) text format and conform to the following model.  

| Name | Type | Description |
| :--- | :--- | :--- |
| `lookupField` | `string` | Must be either `sku` or `external_ref` of a product. |
| `lookupValue` | `string` | The value used to lookup the product. |
| `quantity` | `integer` | The quantity to apply based on the action. |
| `action` | `string` | Must be one of the  following; `increment`, `decrement` or `matchAvailable` depending on the action you want to perform. |

## Using Inventory Import Integration Files

To invoke the inventory import, you must invoke the webhook created when you configure the Inventory Import integration and supply the Gzip file URLs as part of the payload. See [Importing your Inventory Data](#importing-your-inventory-data). We recommend that URLs are signed with an expiration date. See [Sharing objects using presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html).

### Body

| Name | Required | Type | Description |
| :--- | :--- | :--- | :--- |
| `gzipFileUrls` | Required | `string` | The Gzip file URls for the JSON files you want to import in the format `https://{path}/products-inventory.jsonl.gz` where `path` is the path to your Gzip file. You can specify more than one. We recommend aligning the number of products per file with the `pageSize`, as processing each page requires rereading the file. |
| `fileIndex` | Optional | `integer` | The zero based index of the gzip file to start with. The default is zero. This is useful to restart processing in case of failure. |
| `PageSize` | Optional | `integer` | The number of products to process from a given file in a `paged` manner. The default is `500` and the upper limit depends on the number of custom attributes, files and variations. Tuning may be required to find the optimal page size. |
| `page` | Optional | `integer` | Execution start page index. |

### Request Example

```json
{
    "gzipFileUrls": [
        "https://{path}/{file-name}.jsonl.gz"
    ],
    "fileIndex": 0,
    "pageSize": 1000,
    "page": 0
}
```

## Prerequisites

You must have a JSON file configured that defines the price data you want to import. See [Inventory Import Integration File Format](#inventory-import-integration-file-format).

## Configuring the Inventory Import Integration

Once you have met the [Prerequisites](#prerequisites), you are ready to configure the inventory import integration in **Integrations Hub**.

1. In Commerce Manager, go to the store where you want to import inventory data.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, click **Commerce Inventory Import**. The **Commerce Inventory Import** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** are displayed. **URL** is the webhook that consumes your Gzip files. 
1. Click **Next**. The **Commerce Configuration** page is displayed.
1. Complete the information in the **Commerce Configuration** page. 

    1. Enter: 

        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.

            You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. See [Application Keys](/docs/api/application-keys/application-keys-introduction).

        - **Keep Alive Flag** - Turn on the **Keep Alive Flag** toggle if you want to specify keep alive intervals for this integration.
        - **Keep Alive Interval** - Specify keep alive interval for this integration. Default value is 10000.
        - **Throttle Interval** - Specify throttle interval for this integration. Default value is 125. This supports staying within rate limits.
        - **Throttle Limit** - Specify throttle request limit interval for this integration. Default value is 3. This supports staying within rate limits.
        - **Token URL** - Your Commerce API Token URL. For example, `api.motlin.com/oauth/<access_token>` (EU) or `useast.api.elasticpath.com/oauth/<access_token>` (US).

    1. Click **Connect**. The **Integration Hub** uses your current store credentials to automatically connect you to your store.
    1. Once you have successfully connected to Commerce, you can configure the following:

        - **Elapsed Execution Time Cutoff** - The number of seconds to wait before the inventory import is stopped, if page processing has halted for any reason. This may need to be increased if the number of products being processed for the store is exceptionally large.
        - **Default Page Size** - The default page size processed when importing.
        - **Log Level** - From **Log Level** list, select the level of logging.
        - **Product Batch Size** - The maximum product batch size is 100. If you configure the **Product Batch Size** to a value greater than 100, the integration automatically adjusts the value to 100.
    
1. Click **Finish**. Your integration is enabled. You must enable an Inventory Import integration on each store where you want to import your inventory data.  

## Importing your Inventory Data

You can perform the inventory import using Postman. 

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Commerce Inventory Import**. You must have configured an Inventory Import integration before you can import any resources into this store. See [Configuring the Inventory Import Integration](##configuring-the-inventory-import-integration).
1. From **Summary** > **Trigger Details**, click **Gzip File URL Handler** to display the webhook.
1. Select **Copy to Clipboard** to copy the URL.
1. Go to Postman.
1. Open `POST {{gzip-file-url-handler-webhook-url}}` where `*{{gzip-file-url-handler-webhook-url}}*` is the webhook you copied in step 5.
1. In **Body**, add the list of Gzip file URLs for the JSON files you want to import. See [Inventory Import Integration File Format](#inventory-import-integration-file-format).
11. Run `POST {{gzip-file-url-handler-webhook-url}}`.
12. When the import has finished, go to your store to see all the resources you just imported.

## Troubleshooting the Inventory Import Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

Select **Retry** to initiate an execution again.

## Demo

<iframe width="560" height="315" src="https://www.youtube.com/embed/gVa6sOaoIi0" title="Integrations Hub - Inventory Import" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Commerce Node Import

The Commerce Node Import is a utility in the **Integrations Hub** in Commerce Manager that enables you to import Commerce node data to your Commerce store. The Commerce Node Import utility can import:

- Node data files of any size.
- Localized node names and descriptions.

An example of how node data is imported using a Node Import integration is described below.

1. Create a JSON file with the node data you want to import. You can have more than one JSON file, depending on your requirements. See [Node Import Integration File Format](#node-import-integration-file-format).
1. Configure a Node Import integration in the store where you want to import the node data. This creates the webhooks that consumes the message and JSON files when you send the API request to import the node data.
1. In Postman, run `POST {{webhook-url}}` request. As part of the request, you must supply the Gzip file URLs for the JSON files you want to process as part of the import. See [Using Node Import Integration Files](#using-node-import-integration-files).

    - The Node Import integration processes your Gzip files.
    - The nodes are imported to the store.

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/PlTT_uLuhak" title="Using the Node Import integration" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Node Import Integration File Format

The data that you provide to the Node Import integration must conform to [JSON Lines](https://jsonlines.org/) text format and conform to the following model.  [A JSON Schema specification for this format is available here.](/assets/composer/node-import/node-schema.json)

| Name | Type | Description |
| :--- | :--- | :--- |
| `slug` | `string` | A label for the node that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. |
| `hierarchySlug` | `string` | A label for the hierarchy that the node belongs to. It is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. |
| `parentSlug` | `string` | A label for a parent node that a node belongs to. If this is blank, the node is a parent node. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. |
| `name` | `array` | An array of localized names for the node.  See the definition of the [name](#the-name-object) object below. |
| `description` | `array` | An array of localized descriptions for the node.  See the definition of the [description](#the-description-object) object below. |
| `shopper_attributes` | `object` | An object consisting of key-value pairs that represent any required custom shopper-visible attributes for the node. See the [Example Node Object](#example-node-object) section for an example. |
| `admin_attributes` | `object` | An object consisting of key-value pairs that represent any required custom admin-only-visible attributes for the node. See the [Example Node Object](#example-node-object) section for an example.  |

## The `name` Object

If your store supports multiple languages, you can localize node names and descriptions. You can have as many locales as you want.

Name | Type | Description |
| :--- | :--- | :--- |
| `locale` | `string` | The language code, for example, "fr-CA" or "en". |
| `value` | `string` | A localized name for the node. |

## The `description` Object

If your store supports multiple languages, you can localize node names and descriptions. You can have as many locales as you want.

Name | Type | Description |
| :--- | :--- | :--- |
| `locale` | `string` | The language code, for example, "fr-CA" or "en". |
| `value` | `string` | A localized description for the node. |

## Example Node Object

Below is a sample JSON object that properly represent a node in the proper format.

```json
{
  "name": [{
    "locale": "en",
    "value": "node name in english"
  }],
  "description": [{
    "locale": "en",
    "value": "node description in english"
  }],
  "slug": "nodeslug",
  "hierarchySlug": "hierarchyslug",
  "parentSlug": "parent node slug",
  "shopper_attributes": {
    "shopper-attribute1": "shopper-attribute-value1"
  },
  "admin_attributes": {
    "admin-attribute1": "admin-attribute-value1"
  }
}
```

## Using Node Import Integration Files

To invoke the node import, you must invoke the webhook created when you configure the Node Import integration and supply the Gzip file URLs as part of the payload. See [Importing your Node Data](#importing-your-node-data). We recommend that URLs are signed with an expiration date. See [Sharing objects using presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html).

### Body

| Name | Required | Type | Description |
| :--- | :--- | :--- | :--- |
| `gzipFileUrls` | Required | `string` | An array of Gzip file URls for the JSON files you want to import in the format `https://{path}/nodes.jsonl.gz` where `path` is the path to your Gzip file. We recommend aligning the number of products per file with the `pageSize`, as processing each page requires rereading the file. |
| `fileIndex` | Optional | `integer` | The zero based index of the gzip file to start with. The default is zero. This is useful to restart processing in case of failure. |
| `pageSize` | Optional | `integer` | The number of products to process from a given file in a `paged` manner. The default is `500` and the upper limit depends on the number of custom attributes, files and variations. Tuning may be required to find the optimal page size. |
| `page` | Optional | `integer` | The number of pages handled during import. |

### Request Example

```json
{
    "gzipFileUrls": [
        "https://{path}/nodes.jsonl.gz"
    ],
    "fileIndex": 0,
    "pageSize": 1000,
    "page": 0
}
```

## Prerequisites

1. The store where you are importing your node data must already have the hierarchies defined. The Node Import does not create hierarchies as part of the import.
1. You must have a gzipped JSON file configured that defines the node data you want to import. See [Node Import Integration File Formats](#product-import-integration-file-formats).

## Configuring the Node Import Integration

Once you have met the [Prerequisites](#prequisites), you are ready to configure the node import integration in **Integrations Hub**.

1. In Commerce Manager, go to the store where you want to import node data.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, click **Commerce Node Import**. The **Commerce Node Import** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** are displayed. **URL** is the webhook that consumes your Gzip files. 
1. Click **Next**. The **Commerce Configuration** page is displayed.
1. Complete the information in the **Commerce Configuration** page. 

    1. For **Log Level**, from **Value** list, select the level of logging. 
    1. Enter: 

        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.

            You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. See [Application Keys](/docs/commerce-manager/application-keys/application-keys-cm).

    1. Click **Connect**. The **Integration Hub** uses your current store credentials to automatically connect you to your store.
    1. Once you have successfully connected to Commerce, you can configure the following:

        | Option | Description                                                                                                                                                                                                               |
        |:--- |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
        | **Token URL**  | Your Commerce API Token URL. For example, `https://api.motlin.com/oauth/<access_token>` (EU) or `https://useast.api.elasticpath.com/oauth/<access_token>` (US).                                        |
        | **Elapsed Execution Time Cutoff** | The number of seconds to wait before the node import is stopped, if page processing has halted for any reason. This may need to be increased if the number of nodes being processed for the store is exceptionally large. |
        | **Default Page Size** | The default page size processed when importing.                                                                                                                                                                           |

1. Click **Finish**. Your integration is enabled. You must enable a Node integration on each store where you want to import your node data set.  

## Importing your Node Data

You can perform the node import using Postman. 

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Commerce Node Import**. You must have configured a Node Import integration before you can import any resources into this store. See [Configuring the Node Import Integration](##configuring-the-node-import-integration).
1. From **Summary** > **Trigger Details**, click **Paged Node Loader** to display the webhook.
1. Select **Copy to Clipboard** to copy the URL.
1. Go to Postman.
1. Open `POST {{webhook-url}}` where *webhook-url* is the webhook you copied in step 5.
1. In **Body**, add the list of Gzip file URLs for the JSON files you want to import. See [Node Import Integration File Format](#node-import-integration-file-format).
11. Run `POST {{webhook-url}}`.
12. When the import has finished, if you go to your store, you should see all the resources you just imported.

## Troubleshooting the Node Import Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

Select **Retry** to initiate an execution again.

## Demo

<iframe width="560" height="315" src="https://www.youtube.com/embed/PlTT_uLuhak" title="Integrations Hub - Node Import" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Commerce Node Product Association Import

The Commerce Node Product Association Import is a utility in the **Integrations Hub** in Commerce Manager that enables you to quickly and easily update Commerce node product association data in your Commerce store. The Commerce Node Product Association Import utility can import node product association data files of any size. 

An example of how node product association data is updated is described below.

1. Create a JSON file with the node product association data you want to import. You can have more than one JSON file, depending on your requirements. See [Node Product Association Import Integration File Format](#node-product-association-import-integration-file-format).
1. Configure a Node Product Association Import integration in the store where you want to import the node product association data. This creates the webhooks that consumes the message and JSON files when you send the API request to import the node product association data.
1. In Postman, run `POST {{webhook-url}}` request. As part of the request, you must supply the Gzip file URLs for the JSON files you want to process as part of the import. See [Using Node Product Association Import Integration Files](#using-node-product-association-import-integration-files).

    - The Node Product Association Import integration processes your Gzip files.
    - The node product association data are imported to the store.

## Node Product Association Import Integration File Format

The data that you provide to the Node Product Association Import integration must conform to [JSON Lines](https://jsonlines.org/) text format and conform to the following model.  

| Name | Type | Description |
| :--- | :--- | :--- |
| `slug` | `string` | A label for the node that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. |
| `hierarchySlug` | `string` | A label for the hierarchy that the node belongs to. It is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. |
| `products` | `string` | An array of product SKUs. |

An example of a Node Product Association Import integration file is shown below:

```json
{
  "slug": "example-slug",
  "hierarchySlug": "example-hierarchy",
  "products": [
    "test-product-sku-1",
    "test-product-sku-2"
  ]
}
```

## Using Node Product Association Import Integration Files

To invoke the node product association import, you must invoke the webhook created when you configure the Node Product Association Import integration and supply the Gzip file URLs as part of the payload. See [Importing your Node Product Association Data](#importing-your-node-data). We recommend that URLs are signed with an expiration date. See [Sharing objects using presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html).

### Body

| Name | Required | Type | Description |
| :--- | :--- | :--- | :--- |
| `gzipFileUrls` | Required | `string` | An array of Gzip file URls for the JSON files you want to import in the format `https://{path}/associations.jsonl.gz` where `path` is the path to your Gzip file. We recommend aligning the number of products per file with the `pageSize`, as processing each page requires rereading the file. |
| `fileIndex` | Optional | `integer` | The zero based index of the gzip file to start with. The default is zero. This is useful to restart processing in case of failure. |
| `PageSize` | Optional | `integer` | The number of products to process from a given file in a `paged` manner. The default is `100`. Tuning may be required to find the optimal page size. |
| `page` | Optional | `integer` | The number of pages handled during import. |

### Request Example

```json
{
    "gzipFileUrls": [
        "https://{path}/associations.jsonl.gz"
    ],
    "fileIndex": 0,
    "pageSize": 1000,
    "page": 5
}
```

## Prerequisites

1. You must have a gzipped JSON file configured that defines the node product association data you want to import. See [Node Product Association Import Integration File Formats](#node-product-association-import-integration-file-format).
1. The store where you are updating your node product association data must have the nodes and products referenced in the node product association import integration file already defined. The Node Product Association Import does not create the products and nodes as part of the import.

## Configuring the Node Product Association Import Integration

Once you have met the [Prerequisites](#prequisites), you are ready to configure the node product association import integration in **Integrations Hub**.

1. In Commerce Manager, go to the store where you want to import node data.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, click **Commerce Node Product Association Import**. The **Commerce Node Product Association Import** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** are displayed. **URL** is the webhook that consumes your Gzip files. 
1. Click **Next**. The **Commerce Configuration** page is displayed.
1. Complete the information in the **Commerce Configuration** page. 

    1. For **Log Level**, from **Value** list, select the level of logging. 
    1. Click **+ Add Value** to add another level of logging.
    1. Enter: 

        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.

            You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. See [Application Keys](/docs/commerce-manager/application-keys/application-keys-cm).

        The table below describes the options you can configure. 

       | Option | Description |
       |:--- | :--- |
       | **Keep Alive Flag** |  Turn on the **Keep Alive Flag** toggle if you want to specify keep alive intervals for this integration. |
       | **Keep Alive Interval** | Specify keep alive interval for this integration. Default value is 10000. |
       | **Throttle Interval** | Specify throttle interval for this integration. Default value is 125. This supports staying within rate limits. |
       | **Throttle Limit**  | Specify throttle request limit interval for this integration. Default value is 3. This supports staying within rate limits. |
       | **Token URL**  | Your Commerce API Token URL. For example, `useast.api.elasticpath.com/oauth/access_token` (EU) or `useast.api.elasticpath.com/oauth/access_token` (US). |

1. Click **Connect**. 
1. Once you have successfully connected to Commerce, you can configure the following:

    | Option | Description |
    |:--- | :--- |
    | **Elapsed Execution Time Cutoff** | The number of seconds to wait before the node product association import is stopped, if page processing has halted for any reason. This may need to be increased if the number of associations being processed for the store is exceptionally large. |
    | **Default Page Size** | The default page size processed when importing. |
    | **Maximum Hierarchy Depth** | From **Maximum Hierarchy Depth** list, select the depth of parent/child levels you want. The default is 3. |

1. Click **Finish**. Your integration is enabled. You must enable a Node Product Association Import integration on each store where you want to import your node Product Association data set.  

## Importing your Node Product Association Data

You can perform the node product association data import using Postman. 

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Commerce Node Product Association Import**. You must have configured a Node Product Association Import integration before you can import any resources into this store. See [Configuring the Node Product Association Import Integration](#configuring-the-node-product-association-import-integration).
1. From **Summary** > **Trigger Details**, click **Paged Node Product Association Loader** to display the webhook.
1. Select **Copy to Clipboard** to copy the URL.
1. Go to Postman.
1. Open `POST {{webhook-url}}` where *webhook-url* is the webhook you copied in step 5.
1. In **Body**, add the list of Gzip file URLs for the JSON files you want to import. See [Node Product Association Import Integration File Format](#node-product-association-import-integration-file-format).
11. Run `POST {{webhook-url}}`.
12. When the import has finished, go to your store to see the resources you just imported.

## Troubleshooting the Node Product Association Import Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

Select **Retry** to initiate an execution again.

## Demo

<iframe width="560" height="315" src="https://www.youtube.com/embed/uDMdkOg5Lxw" title="Integrations Hub - Node Product Association" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Commerce Price Import

The Commerce Price Import is a utility in the **Integrations Hub** in Commerce Manager that enables you to import Commerce price data from one Commerce store to another. The Commerce Price Import utility can import:

- Price data files of any size. 
- Tier and sale pricing associated with prices.

:::caution

The Price Import integration does not support bundles.

:::

An example of how price data is imported using a Price Import integration is described below.

1. Create a JSON file with the price data you want to import. You can have more than one JSON file, depending on your requirements. See [Price Import Integration File Format](#price-import-integration-file-format).
1. Configure a Price Import integration in the store where you want to import the price data. This creates the webhooks that consumes the message and JSON files when you send the API request to import the price data.
1. In Postman, run `POST {{webhook-url}}` request. As part of the request, you must supply the Gzip file URLs for the JSON files you want to process as part of the import. See [Using Price Import Integration Files](#using-price-import-integration-files).

    - The Price Import integration processes your Gzip files.
    - The prices are imported to the store.

## Price Import Integration File Format

The data that you provide to the Price Import integration must conform to [JSON Lines](https://jsonlines.org/) text format and conform to the following model.  The [price JSON schema file](/assets/ih-price-importer-schema.json) can be used to validate the format of your price objects.

| Name | Type | Description |
| :--- | :--- | :--- |
| `sku` | `string` | The unique stock keeping unit of the product. |
| `priceBookName` | `string` | The name of the pricebook. |

## The `Prices` object

 Each product SKU can have prices in multiple currencies.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `currency` | `string`|  The three-letter ISO code for the currency associated with this price. |
| `amount` | `integer` | The price in the lowest denomination for the specified currency.  |
| `tax_inclusive` | `boolean` | Whether this price includes tax. Default is `false`. |

## The `tiers` object

Each tier can only have one currency within the same block.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `tiers: <key>` | `object` | The name of the tier, such as `Pencils`. Please ensure that camelCase or snake_case is used |
| `tiers: <key>: minimum_quantity` | `integer` | The minimum quantity defined for the specified price. |
| `tiers: <key>: amount` | `integer` | The price for each quantity. |

## The `sales` object

Each sale can only have one sale within the same block.

| Attribute | Type | Description |
| :--- | :--- | :--- |
| `sales: <key>` | `object` | The name of the sale, such as `summerSale`. Please ensure that camelCase or snake_case is used |
| `sales: <key>: schedule` | `object` | The schedule of the sale. Contains an optional `valid_from` and `valid_to` parameter for the start and end date of the sale. |

## Example Price Object

```json
{
  "sku": "productSku",
  "priceBookName": "priceBookName",
  "prices": [
    {
      "currency": "USD",
      "amount": 10000,
      "tax_inclusive": false,
      "tiers": [
        {
          "name": "tierName",
          "minimum_quantity": 5,
          "amount": 90000
        }
      ]
    }
  ],
  "sales": [
    {
      "name": "saleName",
      "schedule": {
        "valid_from": "2022-05-03T20:47:54.068Z",
        "valid_to": "2022-05-28T20:47:57.068Z"
      },
      "salePrices": [
        {
          "currency": "USD",
          "amount": 80000,
          "tax_inclusive": false,
          "tiers": [
            {
              "name": "tierName",
              "minimum_quantity": 5,
              "amount": 80000
            }
          ]
        }
      ]
    }
  ]
}
```

## Using Price Import Integration Files

To invoke the price import, you must invoke the webhook created when you configure the Price Import integration and supply the Gzip file URLs as part of the payload. See [Importing your Price Data](#importing-your-price-data). We recommend that URLs are signed with an expiration date. See [Sharing objects using presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html).

### Body

| Name | Required | Type | Description |
| :--- | :--- | :--- | :--- |
| `gzipFileUrls` | Required | `string` | The Gzip file URls for the JSON files you want to import in the format `https://{path}/products-price.jsonl.gz` where `path` is the path to your Gzip file. You can specify more than one. We recommend aligning the number of products per file with the `pageSize`, as processing each page requires rereading the file. |
| `fileIndex` | Optional | `integer` | The zero based index of the gzip file to start with. The default is zero. This is useful to restart processing in case of failure. |
| `PageSize` | Optional | `integer` | The number of products to process from a given file in a `paged` manner. The default is `500` and the upper limit depends on the number of custom attributes, files and variations. Tuning may be required to find the optimal page size. |
| `page` | Optional | `integer` | The number of pages handled during import. |

### Request Example

```json
{
    "gzipFileUrls": [
        "https://{path}/product-price.jsonl.gz"
    ],
    "fileIndex": 0,
    "pageSize": 1000,
    "page": 0
}
```

## Prerequisites

1. The store where you are importing your price data must already have the pricebooks defined. The Price Import does not create pricebooks as part of the import.
1. You must have a JSON file configured that defines the price data you want to import. See [Price Import Integration File Formats](#price-import-integration-file-formats).

## Configuring the Price Import Integration

Once you have met the [Prerequisites](#prequisites), you are ready to configure the price import integration in **Integrations Hub**.

1. In Commerce Manager, go to the store where you want to import price data.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, click **Commerce Price Import**. The **Commerce Price Import** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** are displayed. **URL** is the webhook that consumes your Gzip files. 
1. Click **Next**. The **Commerce Configuration** page is displayed.
1. Complete the information in the **Commerce Configuration** page. 

    1. **Commerce Connection** details.

        - **Client-ID**  - Your Commerce Client ID.
        - **Client-Secret** - Your Commerce Client Secret.

            You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. See [Application Keys](/docs/commerce-manager/application-keys/application-keys-cm).

        -  **Token URL** - Your Commerce API Token URL. For example, `https://api.motlin.com/oauth/<access_token>` (EU) or `https://useast.api.elasticpath.com/oauth/<access_token>` (US).
        - **Keep Alive Flag** - Turn on the **Keep Alive Flag** toggle if you want to specify keep alive intervals for this integration.
        - **Keep Alive Interval** - Specify keep alive interval for this integration. Default value is 10000.
        - **Throttle Interval** - Specify throttle interval for this integration. Default value is 125. This supports staying within rate limits.
        - **Throttle Limit** - Specify throttle request limit interval for this integration. Default value is 3. This supports staying within rate limits.

    1. Click **Connect**. The **Integration Hub** uses your current store credentials to automatically connect you to your store.
    1. **Elapsed Execution Time Cutoff** is the number of seconds to wait before the node import is stopped, if page processing has halted for any reason. This may need to be increased if the number of nodes being processed for the store is exceptionally large.
    1. **Default Page Size** is the default page size processed when importing.
    1. **Log Level** - From **Log Level** list, select the level of logging.
    
1. Click **Finish**. Your integration is enabled. You must enable a Price Import integration on each store where you want to import your price data.  

## Importing your Price Data

You can perform the price import using Postman. 

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Commerce Price Import**. You must have configured a Price Import integration before you can import any resources into this store. See [Configuring the Price Import Integration](##configuring-the-price-import-integration).
1. From **Summary** > **Trigger Details**, click **Gzip File URL Handler** to display the webhook.
1. Select **Copy to Clipboard** to copy the URL.
1. Go to Postman.
1. Open `POST {{gzip-file-url-handler-webhook-url}}` where `*{{gzip-file-url-handler-webhook-url}}*` is the webhook you copied in step 5.
1. In **Body**, add the list of Gzip file URLs for the JSON files you want to import. See [Price Import Integration File Format](#price-import-integration-file-format).
11. Run `POST {{gzip-file-url-handler-webhook-url}}`.
12. When the import has finished, if you go to your store, you should see all the resources you just imported.

## Troubleshooting the Price Import Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

Select **Retry** to initiate an execution again.

## Demos

<iframe width="560" height="315" src="https://www.youtube.com/embed/_2e1Va_WAZI" title="Integrations Hub - Configuring Price Importer" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Commerce Product Import

The Commerce Product Import is a utility in the **Integrations Hub** in Commerce Manager that enables you to import Commerce product data from one Commerce store to another. The Commerce Product Import utility can import:

- Product data files of any size. 
- Product variations. 
- Any media files available with products.
- Localized product names and descriptions.

:::caution

You cannot import bundles using the Product Import integration.

:::

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/q4lYomkDxD8" title="Using the Product Import integration" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

An example of how product data is imported using a Product Import integration is described below.

1. Create a JSON file with the product data you want to import. You can have more than one JSON file, depending on your requirements. See [Product Import Integration File Format](#product-import-integration-file-format).
1. Configure a Product Import integration in the store where you want to import the product data. This creates the webhooks that consumes the message and JSON files when you send the API request to import the product data.
1. In Postman, run `POST {{gzip-file-url-handler-webhook-url}}` request. As part of the request, you must supply the Gzip file URLs for the JSON files you want to process as part of the import. See [Using Product Import Integration Files](#using-product-import-integration-files).

    - The Product Import integration processes your Gzip files.
    - The products are imported to the store.

## Product Import Integration File Format

The data that you provide to the Product Import Integration must conform to [JSON Lines](https://jsonlines.org/) text format and conform to the following product model.  The [Product Import JSON Schema](/assets/ih-product-import-schema.json) can be used to validate that your individual product objects are in the correct format.

| Name            | Type     | Description                                                                                                                                                                                                                                    |
|:----------------|:---------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name`          | `array`  | An array of names represented as [locale](#the-locales-object) objects.                                                                                                                                                                        |
| `description`   | `array`  | An array of descriptions represented as [locale](#the-locales-object) objects.                                                                                                                                                                 |
| `sku`           | `string` | The unique stock keeping unit of the product.                                                                                                                                                                                                  |
| `slug`          | `string` | A label for the product that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. By default, the product name is used as the slug. |
| `productType`   | `string` | Always: `product`.                                                                                                                                                                                                                             |
| `status`        | `string` | The status for the product, either `draft` or `live`.                                                                                                                                                                                          |
| `commodityType` | `string` | The commodity type, either `physical` or `digital`.                                                                                                                                                                                            |
| `media`         | `object` | The media available with this product, for example, images. See [media object](#the-media-object).                                                                                                                                             |
| `mpn`           | `string` | The manufacturer part number of the product.                                                                                                                                                                                                   |
| `attributes`    | `object` | The attributes defined for a product. See [attributes object](#the-attributes-object).                                                                                                                                                         |
| `variation`     | `object` | The variations defined for a product. See [variation object](#the-variation-object).                                                                                                                                                           |

### The `locales` Object

Locales must be specified for product names and descriptions. You can have as many localized names and descriptions as needed.

| Name     | Type     | Description                                                                                                                                         |
|:---------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------|
| `locale` | `string` | A 2-character [ISO 639-1 locale code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) that specifies the language of the associated `value`. |
| `value`  | `string` | The localized value.                                                                                                                                |

### The `media` object

| Name   | Type     | Description                                                       |
|:-------|:---------|:------------------------------------------------------------------|
| `type` | `string` | The type of resource object. For example, `main_image` or `file`. |
| `url`  | `string` | The URL of the resource.                                          |

### The `attributes` object

| Name                 | Type     | Description                                                                                          |
|:---------------------|:---------|:-----------------------------------------------------------------------------------------------------|
| `templateSlug`       | `string` | Specifies a unique slug identifier for the attribute.                                                |
| `templateAttributes` | `object` | The attributes you want to import. See [templateAttributes object](#the-template-attributes-object). |

### The `templateAttributes` object

| Name        | Type     | Description                                                                                   |
|:------------|:---------|:----------------------------------------------------------------------------------------------|
| `fieldSlug` | `string` | The slug that contains the attribute you wish to create an entry for.                         |
| `type`      | `string` | Specifies the type of field. Values can be `date`, `string`, `boolean`, `float` or `integer`. |
| `value`     | `string` | The value of the field.                                                                       |

### The `variation` object

| Name          | Type     | Description                                                                                                                                                                                                                                      |
|:--------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `variantSlug` | `string` | A label for the variation that is used in the URL paths. A slug can contain any combination of letters, numbers, periods, hyphens, and underscores. NO spaces or other characters are allowed. By default, the product name is used as the slug. |
| `optionName`  | `object` | The options available for this variation.                                                                                                                                                                                                        |

### Example Product Objects

#### Example 1 - Product with a Single Template

```json
{
  name: [
    {
      locale: "en",
      value: "en-name",
    },
  ],
  description: [
    {
      locale: "en",
      value: "en-description",
    },
  ],
  slug: "slug",
  sku: "sku",
  productType: "product",
  status: "draft",
  commodityType: "digital",
  mpn: "mpn",
  attributes: [
    {
      templateSlug: "products(ps)",
      templateAttributes: [
        {
          fieldSlug: "dateAttribute",
          type: "date",
          value: "2021-05-28T15:59:48.790Z",
        },
        {
          fieldSlug: "integerAttribute",
          type: "integer",
          value: 1,
        },
        {
          fieldSlug: "stringAttribute",
          type: "string",
          value: "dolore pariatur enim cillum",
        },
      ],
    },
  ],
}
```

#### Example 2 - Product with One Variant

```json
{
  name: [
    {
      locale: "en",
      value: "en-name",
    },
  ],
  slug: "slug",
  sku: "sku",
  productType: "product",
  status: "draft",
  commodityType: "digital",
  skuProducts: [
    {
      slug: "skuSlug",
      sku: "skuSku",
      productType: "sku",
      name: [
        {
          locale: "skuLocale",
          value: "skuName",
        },
      ],
      status: "live",
      commodityType: "digital",
      variation: [
        {
          variantSlug: "variantSlug1",
          optionName: "optionName",
        },
      ],
    },
  ],
}
```

## Using Product Import Integration Files

To invoke the product import, you must invoke the webhook created when you configure the Product Import integration and supply the Gzip file URLs as part of the payload. See [Importing your Product Data](#importing-your-product-data). We recommend that URLs are signed with an expiration date. See [Sharing objects using presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html).

### Body

| Name | Required | Type | Description |
| :--- | :--- | :--- | :--- |
| `gzipFileUrls` | Required | `string` | The Gzip file URls for the JSON files you want to import in the format `https://{path}/products.jsonl.gz` where `path` is the path to your Gzip file. You can specify more than one. We recommend aligning the number of products per file with the `pageSize`, as processing each page requires rereading the file. |
| `fileIndex` | Optional | `integer` | The zero based index of the gzip file to start with. The default is zero. This is useful to restart processing in case of failure. |
| `page` | Optional | `integer` | The number of pages handled during import. |
| `PageSize` | Optional | `integer` | The number of products to process from a given file in a `paged` manner. The default is `500` and the upper limit depends on the number of custom attributes, files and variations. Tuning may be required to find the optimal page size. |

### Request Example

```json
{
    "gzipFileUrls": [
        "https://{path}/products.jsonl.gz"
    ],
    "fileIndex": 0,
    "page": 0,
    "pageSize": 1000
}
```

## Prerequisites

1. The store that you are importing your product data set into must meet the following prerequisites:

    - The templates and attributes defined in the product data that you are importing must exist in the store that you are importing the product data into. 
    - The variations defined in the product data that you are importing must exist in the store that you are importing the product data into. If the variations defined in the product data import have options, you do not need to create those options in your store. The Product Import automatically creates the options for you as part of the product import.

1. You must have a JSON file configured that defines the product data you want to import. See [Product Import Integration File Formats](#product-import-integration-file-formats).

## Configuring the Product Import Integration

Once you have met the [Prerequisites](#prequisites), you are ready to configure the product import integration in **Integrations Hub**.

1. In Commerce Manager, go to the store where you want to import product data.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, click **Commerce Product Import**. The **Commerce Product Import** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** are displayed. **Note**: These fields are blank the first time you configure the integration.

   - **Gzip File URL Handler** - The webhook that consumes your Gzip files. 
   - **Page Product Loader** - The webhook that processes each page of products until all pages are processed.

1. Click **Next**. The **Commerce Connection** page is displayed.
1. Complete the information in the **Commerce Connection** page. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. See [Application Keys](/docs/commerce-manager/application-keys/application-keys-cm).

    - **Client-ID**  - Your Commerce Client ID.
    - **Client-Secret** - Your Commerce Client Secret.

    The table below describes the options you can configure. 

    | Option                  | Description                                                                                                                                                     |
    |:------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Keep Alive Flag**     | Turn on the **Keep Alive Flag** toggle if you want to specify keep alive intervals for this integration.                                                        |
    | **Keep Alive Interval** | Specify keep alive interval for this integration. Default value is 10000.                                                                                       |
    | **Throttle Interval**   | Specify throttle interval for this integration. Default value is 125. This supports staying within rate limits.                                                 |
    | **Throttle Limit**      | Specify throttle request limit interval for this integration. Default value is 3. This supports staying within rate limits.                                     |
    | **Token URL**           | Your Commerce API Token URL. For example, `https://api.motlin.com/oauth/<access_token>` (EU) or `https://useast.api.elasticpath.com/oauth/<access_token>` (US). |

1. Click **Connect**. 
1. Once you have successfully connected to Commerce, you can configure the following:

    | Option                            | Description                                                                                                                                                                                                                     |
    |:----------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    | **Elapsed Execution Time Cutoff** | The number of seconds to wait before the product import is stopped, if page processing has halted for any reason. This may need to be increased if the number of products being processed for the store is exceptionally large. |
    | **Default Page Size**             | The default page size processed when importing.                                                                                                                                                                                 |
    | **Merge Mode**                    | When set, the comparison is made between the existing product and the inbound definition, with only items that have been changed. Default: false                                                                                |
    | **Log Level**                     | From **Log Level** list, select the level of logging.                                                                                                                                                                           |
    | **JavaScript Pre-Process Code Snippet** | A JavaScript code snippet used for pre-processing import records.  This code snippet can be used for custom validation, data augmentation, or other similar use cases.  It is executed against each batch of import records immediately before they are imported and can make any changes to the records or even remove them from the import at runtime. See the default snippet provided in the integration for an example. |

1. Click **Finish**. Your integration is enabled. You must enable a Product Import integration on each store where you want to import your product data set.  

### Merge Mode

Default processing assumes that the inbound product record provides a full representation of the product, allowing a more efficient product loading process. 
However, in scenarios, where there are multiple sources of product information, it might become necessary to use the **Merge Mode**. 
When this option is selected, the product loader will load the existing product, overlaying it with the inbound product before performing any updates. 

The default value is  _false_ (not enabled).

## Importing your Product Data

You can perform the product import using Postman. 

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Commerce Product Import**. You must have configured a Product Import integration before you can import any resources into this store. See [Configuring the Product Import Integration](##configuring-the-product-import-integration).
1. From **Summary** > **Trigger Details**, click **Gzip File URL Handler** to display the webhook.
1. Select **Copy to Clipboard** to copy the URL.
1. Go to Postman.
1. Open `POST {{gzip-file-url-handler-webhook-url}}` where *gzip-file-url-handler-webhook-url* is the webhook you copied in step 5.
1. In **Body**, add the list of Gzip file URLs for the JSON files you want to import. See [Product Import Integration File Format](#product-import-integration-file-format).
11. Run `POST {{gzip-file-url-handler-webhook-url}}`.
12. When the import has finished, if you go to your store, you should see all the resources you just imported.

## Troubleshooting the Product Import Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

Select **Retry** to initiate an execution again.

---

## Commerce Store Configuration Orchestrator

The Commerce Store Configuration Orchestrator is a utility in the Integrations Hub in Commerce Manager that enables you to export and/or import resources from one Commerce store to another. This is useful if, for example, you want to copy a configuration from a store in a development environment to a store in a production environment.

Once you have configured the store configuration orchestrator integration, you can use the integration to:

- **Import** a store configuration from one store to another. The `Import Asynchronous Flow` provides a webhook trigger that accepts a JSON payload containing the store configuration. The Store Configuration Orchestrator Import Action executes and passes the JSON request to apply the imported configurations to a store.
- **Export** a store configuration to a JSON file.  The `Export Synchronous Flow` provides a webhook trigger that invokes the Store Configuration Orchestrator's Export Action and returns the exported store configuration in a JSON file.
- **Delete** existing resources. The `Delete Asynchronous Flow` provides a webhook trigger that invokes the Store Configuration Orchestrator's Delete Action. The asynchronous response is a single data element containing the remaining products.

The following Commerce objects are included when importing/exporting store configurations.

- [Currencies](/docs/api/pxm/currencies/currencies)
- [Templates](/docs/api/flows/flows-service-introduction#templates-in-product-experience-manager)
- [Variations](/docs/api/pxm/products/variations)
- [Variation Options](/docs/api/pxm/products/create-variation-option)
- [Flows](/docs/api/flows/flows-service-introduction)
- [Integrations](/docs/api/integrations/integrations-introduction)
- [Price Books](/docs/api/pxm/pricebooks/price-books-introduction)
- [Hierarchies](/docs/api/pxm/products/hierarchies)
- [Nodes](/docs/api/pxm/products/create-node). Only parent-level nodes are imported or exported. You cannot import or export nested nodes.
- [Catalogs](/docs/api/pxm/catalog/create-catalog)
- [Catalog Rules](/docs/api/pxm/catalog/rules)
- [Payment Gateway](/docs/api/payments/gateways). The following fields are masked when exporting payment gateways: **password**, **username**, **login**, **merchant_account**, **signature**, **stripe_account**, **merchant_id**, **private_key**, **public_key**, **payer_id**. These fields must be replaced by real values before importing the configuration.

A Store Configuration Orchestrator Delete Action deletes [products](/docs/api/pxm/products/products) from a store.

For more information, watch a video.

<iframe width="560" height="315" src="https://www.youtube.com/embed/faInZG1n8y4" title="Using the Store Configuration Orchestrator" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Understanding Environments in Store Configuration Orchestrator

Store Configuration Orchestrator allows you to categorize resources by environments. Here is an example of a [Store Configuration Orchestrator store configuration](/assets/store-configuration-orchestrator-example.json).

During an export, all configuration resources are stored in the `common` environment.

During an import, you can specify resources by environment. This allows you to have resources for your production and development environments in the same JSON file. When you perform a Store Configuration Orchestrator Import Action, you can specify the environment whose resources you want to import. A Store Configuration Orchestrator Import Action always imports resources from the `common` environment. If no environment is specified, only resources from the `common` environment are loaded. See [Configuring the Store Configuration Orchestrator Integration](#configuring-the-store-configuration-orchestrator-integration).

## Best Practices

The steps below are an example of the steps you could follow to copy a configuration from a store in a development environment to a store in a production environment.

1. Go to a development store and configure your integration.
1. Once you are ready to promote your development store to a different environment, execute a Store Configuration Orchestrator Export Action. You could then check this into your source control system, for example.
1. Your CI/CD pipeline can execute a Store Configuration Orchestrator Import Action to import this configuration into a different instance of the integration and import the  configuration from the development store to a different store.

## Configuring the Store Configuration Orchestrator Integration

Once you have [installed Store Configuration Orchestrator](#installing-store-configuration-orchestrator), you are ready to configure the Store Configuration Orchestrator integration in **Integrations Hub**.

1. In Commerce Manager, go to the store from which you want to export, import or delete resources.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, click **Store Configuration Orchestrator**. The **Store Configuration Orchestrator** integration guides you through the steps you need to follow to complete the integration.
1. Click **Configure**. The **Trigger details** are displayed. The **Store Configuration Orchestrator** integration automatically creates the webhooks required for the import, export and delete actions. The first time you configure the integration, no webhooks are displayed. The next time you configure your Store Configuration Orchestrator, the previously created webhooks are displayed. You do not need to change any of the information here.

    :::caution
    Do not configure any API keys for the webhooks. The webhooks are authorized using the `configuration.secret_key` value in the request body.  Configuring an API key directly on the webhook results in a non-functional integration.
    :::

1. Click **Next**. The **Commerce Connection** page is displayed.
1. Complete the information in the **Commerce Connection** page. You can find this information in **SYSTEM** > **Application Keys** in Commerce Manager when logged in as a user with Seller Admin privileges. See [Application Keys](/docs/commerce-manager/application-keys/application-keys-cm).

    - **Client-ID**  - Your Commerce Client ID.
    - **Client-Secret** - Your Commerce Client Secret.
    - **Token URL** - Your Commerce API Token URL. For example, `https://euwest.cm.elasticpath.com/oauth/<access_token>` (EU) or `https://useast.api.elasticpath.com/oauth/<access_token>` (US).

1. Click **Connect** to make sure that the authentication is completed successfully.
1. Click **Next**. The **Store Orchestrator Configuration** page is displayed. The table below describes the options you can configure, depending on the Store Configuration Orchestrator action you are performing.

    | Option | Action | Description |
    |:--- |:--- | :--- |
    | **Delete Batch Size** | Delete Action only. | Specify the page size to query when deleting large volumes of products. Maximum value is 100. |
    | **Delete Batch Limit**  | Delete Action only. | Specify the maximum number of batches to delete at one time. Leave blank to delete all batches. For example, if you set the **Delete Batch Limit** to 5, the first 5 batches of products are deleted. |
    | **Environment**  | Import Action only.  | Specify the environment whose resources you want to import. See [Understanding Environments in Store Configuration Orchestrator](#understanding-environments-in-store-configuration-orchestrator). |
    | **Log Level**  | All actions. | From **Log Level** list, select the level of logging. |

1. Click **Finish**. Your integration is enabled. You must enable a Store Configuration Orchestrator integration on each store from which you want to export, import or delete resources.

## Testing Store Configuration Orchestrator

You can quickly and easily test your configuration by manually invoking a configuration using the following Postman collections. 

- [Store Configuration Orchestrator Postman Collection](/assets/store-configuration-orchestrator.postman_collection.json).
- [Store Configuration Orchestrator Postman Environment](/assets/store-configuration-orchestrator.postman_environment.json).

### Exporting Resources Using Store Configuration Orchestrator Integration

You must have imported the postman collections before performing a Store Configuration Orchestrator Export Action. 

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Store Configuration Orchestrator**. You must have configured a Store Configuration Orchestrator integration before you can export any resources from this store. See [Configuring the Store Configuration Orchestrator Integration](#configuring-the-store-configuration-orchestrator-integration).
1. From **Summary**, select **Export Synchronous** to display the webhook.
1. Select **Copy to Clipboard** to copy the URL.
1. Go to Postman.
1. In the Store Configuration Orchestrator Environment, in the `export-sync-webhook-url` variable, under **CURRENT VALUE**, paste the Export Synchronous URL you copied above.
1. Go to the Store Configuration Orchestrator Collection.
1. Run `GET {{export-sync-webhook-url}}`.
1. When the export has finished, copy the JSON payload. You can use this JSON payload to execute a Store Configuration Orchestrator Import Action. See [Importing Resources Using Store Configuration Orchestrator Integration](#importing-resources-using-store-configuration-orchestrator-integration).

### Importing Resources Using Store Configuration Orchestrator Integration

To import resources using Store Configuration Orchestrator Integration:

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Store Configuration Orchestrator**. You must have configured a Store Configuration Orchestrator integration before you can import any resources into this store. See [Configuring the Store Configuration Orchestrator Integration](#configuring-the-store-configuration-orchestrator-integration).
1. From **Summary**, select **Import Asynchronous** to display the webhook.
1. From **Selected flow** list, select **Import Asynchronous**.
1. Select **Copy to Clipboard** to copy the URL.
1. Go to Postman.
1. In the Store Configuration Orchestrator Environment, open `POST {{import-async-webhook-url}}` request.
1. In the `import-async-webhook-url` variable, under **CURRENT VALUE**, paste the Import Asynchronous URL you copied above.
1. In **Body**, paste the JSON payload that you generated when exporting. See [Exporting Resources Using Store Configuration Orchestrator Integration](#exporting-resources-using-store-configuration-orchestrator-integration).
1. Run `POST {{import-async-webhook-url}}`.
1. When the import has finished, if you go to your store, you should see all the resources you just imported.

### Deleting Resources Using Store Configuration Orchestrator Integration

To delete products using Store Configuration Orchestrator Integration:

1. Go to a store.
1. Go to **COMPOSER** > **Integrations Hub**.
1. Under **Store Management & Configuration**, select **Store Configuration Orchestrator**. You must have configured a Store Configuration Orchestrator integration before you can delete any products from this store. See [Configuring the Store Configuration Orchestrator Integration](#configuring-the-store-configuration-orchestrator-integration).
1. From **Selected flow** list, select **Delete Asynchronous**.
1. Select **Copy to Clipboard** to copy the URL.
1. Go to Postman.
In the Store Configuration Orchestrator Environment, in the `delete-async-webhook-url` variable, under **CURRENT VALUE**, paste the Delete Asynchronous URL you copied above.
1. Open `DELETE {{delete-async-webhook-url}}` request.
1. Run `DELETE {{delete-async-webhook-url}}`.
1. Depending on how you have configured **Delete Batch Limit**, the Store Configuration Orchestrator deletes the batches of products you specified. For example, if you set the **Delete Batch Limit** to 5, the first 5 batches of products are deleted.

## Using Store Configuration Orchestrator Integration

To use Store Configuration Orchestrator Integration:

1. Go to a store.
1. From **COMPOSER** > **Integrations Hub**, go to your Store Configuration Orchestrator integration.
1. From **Summary**, you can view, pause or delete your Store Configuration Orchestrator integration.
1. To reconfigure Store Configuration Orchestrator, go to **Summary** > **Reconfigure**.
1. If there is an update to the Commerce Store Configuration Orchestrator integration, a message is displayed in **Summary**. Click **Update** to update your integration. You are walked through the steps to configure your integration.

## Troubleshooting the Store Configuration Orchestrator Integration

You can debug any issues in **Executions**. Click an execution to see the execution details. The **Logs** shows the output and any errors or warnings.

Select **Retry** to initiate an execution again.

---

## Integrating with Avalara

You can quickly and easily integrate Commerce with Avalara using the **Integrations Hub** in Commerce Manager. Using Avalara Integration, you can commit tax and void tax on specific order events. 

Order changes in Commerce, like creating, fulfilling, and canceling, generate webhook events that cause orders to be created, fulfilled, and canceled in Avalara. The following Commerce event types can be used to generate webhook events.

- `order.created`
- `order.fulfilled`
- `order.paid`
- `order.authorized`
- `order.cancelled`
 
![Avalara Integration](/assets/avalara-integration.png)

:::note
When integrating with third-party providers, we recommend you use the closest region in the third-party service to reduce latency as much as possible. See [Regions and URLs table](/guides/Getting-Started/elastic-path-domains#regions-and-urls).
:::

## Prerequisites

You must have products in Commerce Manager.

## Configuring Avalara Integration

1. In Commerce Manager, go to **COMPOSER > Integrations Hub**.
1. Under **Tax and Shipping**, click **Avalara**. 
1. Click **Configure**. The Avalara integration guides you through the steps you need to follow to complete the integration.
1. Click **Next**. The **Connection** page is displayed.
1. Enter the following details in **Avalara Connection**:
    - **Company Code** - Your company code. 
    - **Avalara APP Version** -  Enter your API version. Default is `1.0`.
    - **Avalara Environment** - Select either **Sandbox** or **Production**.
    - **Avalara UserName** - Your Avalara username.
    - **Avalara Password** - Your Avalara password.
1. Enter the following details in **Commerce Connection**:
    - **Client-ID**  - Your Commerce Client ID.
    - **Client-Secret** - Your Commerce Client Secret.
    - **Token URL** - Your Commerce API Token URL.
    
    **Token URL** for:
    - EU - `https://useast.api.elasticpath.com/oauth/access_token`
    - US - `https://useast.api.elasticpath.com/oauth/access_token`
    
    To collect your **Client-ID** and **Client-Secret**, log into Commerce Manager with Seller Admin privileges and go to **SYSTEM** > **Application Keys**. See [Application Keys](/docs/commerce-manager/application-keys/application-keys-cm).

1. Click **Connect**. The authorization is successfully completed.
1. Click **Next**.
1. In the **Commit Trigger** field, select one of the following order events according to your requirements to initiate the commit transaction:
    - `order.created`
    - `order.fulfilled`
    - `order.paid`
    - `order.authorized`
1. (Optional) Turn on the **Enable Ship from** toggle to enter the **ship from address**. It is enabled by default.
1. (Optional) In the **ship from address** field, click **Edit** and enter the ship from address.
1. In the **Default Tax Code** field, enter your default tax code if your product doesn’t have an associated tax code.
1. Click **Next**. You can see the default **Commit Tax Template** and **Void Tax Template** fields. 
1. (Optional) Click **Edit** to modify **Commit Tax Template** and **Void Tax Template** according to your requirements.
1. Click **Next**. The **Setup Webhooks and flows** page is displayed. From this page, decide which webhooks you want to setup, depending on your requirements. The Avalara Integration automatically creates the webhooks, once you have finished configuring the integration.

    The following toggles are enabled by default:
    - **Enable Commit webhook** : triggers commit transaction
    - **Enable Void webhook** : triggers void transaction
    - **Enable Product extension** : configures product extension flow in Commerce Manager
1. (Optional) Click **Edit** in the **Product extension input** field, to edit the default request in order to setup product extension flow and fields in Commerce depending on your requirements. This integration will create a new template and field in Commerce Manager.
1. (Optional) Click **Edit**, in the **Customer extension input** field, to edit the default request in order to setup customer extension flow and fields in Commerce depending on your requirements.
1. Click **Finish**. Your integration is enabled.

    The new template and attributes will be displayed on the **Configuration** > **Templates** page. Additionally, customer extension flow and fields are also displayed on **SYSTEM** > **Flows** page.

## Using Avalara Integration

The following scenario explains how to pay for an order in Elastic Path Composable Frontend and how you can commit tax and void tax using the Avalara integration.

1. Go to Elastic Path Composable Frontend. It should be integrated with your store in Commerce Manager.
1. Add a product to a cart. In **Order Summary**, you will see that tax has not been included in the order.
1. Click **Checkout**.
1. Enter your **Contact Information** and **Shipping Address**. 
1. Select the **Same as shipping address** checkbox if your **Billing Address** is same as **Shipping Address**
1. Click **Checkout Now**. 
    
    In **Order Summary**, you can now see that the tax has been calculated based on the shipping address.
1. Enter your billing information and click **Pay now** to complete your transaction.
1. Copy **Your order number** from the **Order Complete** page.
1. In Commerce Manager, go to **Store** > **Orders**.
    All orders in the store are displayed.
1. On the **All orders** page, click on your order to view the tax details.
1. Log into your Avalara environment.
1. Go to **Transactions** and search for your order. 
    
    You can see the transaction details and tax summary, and the **Document status** shows **Committed**.
1. (Optional) If you cancel an order in Commerce Manger, the **Document status** in Avalara environment will change to **Voided**.

## Demos

To learn how to configure and use the Avalara Integration, watch the following video:

<iframe width="560" height="315" src="https://www.youtube.com/embed/IIp_bbQN5i8" title="Configuring Avalara" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Components and Integrations

A component is a portion of reusable code that accomplishes a specific task, or connects with an outside service. Several components are strung together to form an integration. Composer offers a wide array of components to accomplish a variety of things. 

In **Components**, you can see a complete list of all the components that Composer provides. 

Select a component for more information about the component, including data sources, connections, and actions.

![epcc component](/assets/epcc_component.png)

In **Integrations**, you can see a complete list of all your integrations. Select an integration, if you want to view or reconfigure the integration.

---

## Instances and Executions

When you are satisfied with an integration and have published a version of it, you can create an instance of the integration.

**Instances** provides an overview of all your current instances for all integrations, including their status, and when the instance was last run.

You can:

- Search and filter on your current instances. 
- Select an instance to open the instance in **Integrations Hub**, if you want to view or reconfigure the integration.

When an instance is run, this is called an execution. 

**Executions** displays the execution details for all your instances. You can inspect execution details and the results of each step of the execution. 

If an instance failed to run, you can review the data that was passed in to the instance when it was invoked.

In addition, you can manually retry an execution. The instance is run again with the same webhook payload that caused it to run initially. 

![manually retry an execution](/assets/monitor_executions.png)

---

## Logs

Monitor allows you to view groups of logs for all the integrations that you have turned on in Composer. Access to logs is critical for building, deploying, and supporting your integrations.

## Log Retention

Logs and step results are retained for 14 days and are purged thereafter.

## Viewing Logs for Integrations

To see logs for all your instances:

1. Go to **Composer** > **Monitor**.
2. Select **Logs**. You see log messages, their timestamps in your local time, the name of the instance and the name of the integration the instance was created from.

![monitor](/assets/monitor.png)

3. To see a log's details, select the log you want for the instance you are interested in.

   ![monitor](/assets/monitor_2.png)

4. Select **View in Execution Context** to view the execution details. The type of information displayed includes:

    - The trigger that created an event.
    - Release data.
    - Any files that caused errors.

![monitor](/assets/monitor_3.png)

## Searching and Filtering Logs

To search for specific messages in your logs, type part of the message into **Search logs** at the top of the page.

![monitor](/assets/monitor_search.png)
mo
For more information on a specific log line, click the log line to view an additional information panel.

Additionally, you can apply filters to your logs. Click the **Filter** list to the right of the search bar and select any of the following options:

- Log Type - For example, apply the **Connection Only** filter if you are searching for authentication issues, such as when a connection fails to receive a token during an automatic refresh. 
- Log Severity - Apply filters to find messages according to their severity level.
  - `fatal` 
  - `Error`
  - `warn`
  - `info`
  - `debug`
  - `trace`
  - `metric` 
- Timestamps - For example, use start date/time and end date/time to create a range to search within.
- Instance - Apply filters to find messages from specific parts of an integration.

![monitor](/assets/monitor_filter.png)

## Viewing Connection Logs

Connections that are used for testing in Builder, and those assigned to deployed instances, create logs. If a connection ever throws a connection error (for example, if the credentials in the connection have expired), you will see that in the connection's logs.

To view a connection's logs, click the log icon to the right of the connection.

## What Gets Logged?

If a component invokes `context.logger.{debug,info,warn,error}()` within its code, the log line is saved in Monitor's logging system.

In addition to logs issuing from components, you will see the following types of log lines in your logs:

| Type           | 	Example	                             | Purpose                                                                                      | 	Log Level |
|----------------|---------------------------------------|----------------------------------------------------------------------------------------------|------------|
| Instance Start | 	Starting Instance 'Sample Instance'	 | Indicates when an instance begins to run.	                                                   | info       |
| Instance End	  | Ending Instance 'Sample Instance'	    | Indicates that an instance ran successfully to completion.                                   | 	info      |
| Step Started   | 	Fetch file from Dropbox	             | Displays the name of the step that was invoked.                                              | 	info      |
| Step Failed	   | `{{ERROR MESSAGE}}`	                    | Indicates that a step of an instance failed to run, and displays the related error message.	 | error      |

## Log Levels

Monitor has the following log levels. Logs are presented with a colored dot to indicate their severity.

![monitor log dots](/assets/monitor_log_dots.png)

---

## Overview(Monitor)

Monitor provides an aggregated view of all of your integration activities with visibility into each execution and the ability to drill into the details of any execution. Filter the logs or executions screens to look for failures across all integrations or filter down to a specific integration or even a specific process flow within a specific integration. Monitor acts as an operational control panel for your business, providing your DevOps teams with one central environment through which to view and manage your federated architectures to alert you via Slack or Email that an integration that runs daily ran successfully.

In **Summary**, you can see the total number of instances you have, including a list of the running instances. Either select an individual instance or select the pane to go to **Instances**.

 In addition, you can see the total number of executions in the last 24 hours. Select the pane to view the details of the executions.

Finally, you can view any attachments you have. 

![Monitor summary](/assets/monitor_summary.png)

---

## Create a Customer

## `POST` Create a customer

```http
https://useast.api.elasticpath.com/v2/customers
```

Creates the customer.

## Parameters

### Headers

| Name            | Required | Type     | Description                                         |
| --------------- | -------- | -------- | --------------------------------------------------- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name           | Required | Type     | Description                                                                                                                                                                |
|----------------| -------- | -------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type`         | Required | `string` | Represents the type of object being returned.                                                                                                                              |
| `name`         | Required | `string` | The full name of the customer.                                                                                                                                             |
| `email`        | Required | `string` | The customer email.                                                                                                                                                        |
| `password`     | Optional | `string` | The customer password.                                                                                                                                                     |
| `external_ref` | Optional | `string` | The unique attribute associated with the customer. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`. |

## Request Example

### Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/customers \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $ {
     "data": {
       "type": "customer",
       "name": "Ron Swanson",
       "email": "ron@swanson.com",
       "external_ref": "16bedceb-8b2d-4f82-a973-b0a8d8432708",
       "password": "mysecretpassword"
     }
   }
```

### Javascript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
});
const customer = {
    name: "Ron Swanson",
    email: "ron@swanson.com",
    password: "mysecretpassword",
};
Moltin.Customers.Create(customer).then((customer) => {
    // Do something
});
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "customer",
        "id": "fc4679bf-f8a8-4029-bc67-945f74b756a0",
        "name": "Ron Swanson+6",
        "email": "ron+6@swanson.com",
        "external_ref": "16bedceb-8b2d-4f82-a973-b0a8d8432708",
        "password": true,
        "meta": {
            "timestamps": {
                "created_at": "2017-01-11T18:44:45Z",
                "updated_at": "2017-05-31T04:12:12Z"
            }
        }
    }
}
```

---

## Customer API Overview

Use the Customer API to manage customer details, addresses, and other information.

The Customer API allows you to generate tokens inside your client-side applications to authenticate requests to get all customer orders.

- [Customer tokens](/docs/customer-management/customer-management-api/customer-tokens)

You are able to use a [customer](/docs/customer-management/customer-management-api/customer-tokens) token with an [implicit access token](/docs/api/authentication/create-an-access-token). This is recommended for client-side interactions. Alternatively, you can use a [client_credentials access token](/docs/api/authentication/create-an-access-token). This is recommended for back-end interactions.

## The `Customer` Object

| Attribute      | Type      | Description                                               |
|:---------------|:----------|:----------------------------------------------------------|
| `id`           | `string`  | The unique identifier for this customer.                  |
| `type`         | `string`  | The `type` represents the object being returned.          |
| `name`         | `string`  | The `name` of the customer.                               |
| `email`        | `string`  | The `email` of the customer.                              |
| `password`     | `boolean` | `true` if the customer has a password, `false` otherwise. |
| `external_ref` | `string`  | The optional external ID reference. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`. |

## The `meta` Object

| Attribute         | Type     | Description                               |
|:------------------|:---------|:------------------------------------------|
| `meta.created_at` | `string` | The creation date of this `customer`.     |
| `meta.updated_at` | `string` | The last updated date of this `customer`. |

### Sample response

```json
{
    "data": {
        "type": "customer",
        "id": "f260b17a-390f-4b37-bf9d-f62c45a95865",
        "name": "Ron Swanson",
        "email": "ron@swanson.com",
        "external_ref": "16bedceb-8b2d-4f82-a973-b0a8d8432708",
        "password": true,
        "meta": {
            "timestamps": {
                "created_at": "2017-01-11T18:44:45Z",
                "updated_at": "2017-05-31T04:12:12Z"
            }
        }
    }
}
```

---

## Customer Tokens

Commerce provides a basic `/tokens` endpoint using which you can authenticate using a [password](#using-a-username-and-password) or [Single Sign-On through OpenID Connect](#using-openid-connect). With this endpoint, you can allow customers to manage their [addresses](/docs/api/customer-addresses/addresses-introduction) or [get orders](/docs/api/carts/get-customer-orders) by `customer`.

## The `customer token` Object

| Attribute     | Type        | Description                                    |
|:--------------|:------------|:-----------------------------------------------|
| `id`          | `string`    | The unique identifier for this token.          |
| `type`        | `string`    | The type represents the object being returned. |
| `customer_id` | `string`    | The ID of the customer from which the token is generated. |
| `token`       | `string`    | The token to be used for other endpoints. |
| `expires`     | `timestamp` | The epoch time that this token expires at. It is 24 hours from the moment the token is generated. |

:::note
The tokens returned should be treated as opaque and not decoded, as the internals may change over time.

:::

### Sample response

```json
{
    "data": {
        "type": "token",
        "id": "36f05940-0d38-411a-8909-3aea58bc1f09",
        "customer_id": "79cc0486-bbdf-491b-a0a2-722383b6288b",
        "token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiI3OWNjMDQ4Ni1iYmRmLTQ5MWItYTBhMi03MjIzODNiNjI4OGIiLCJuYW1lIjoiUm9uIFN3YW5zb24iLCJleHAiOjE1MTA2ODQyMDAsImlhdCI6MTUxMDU5NzgwMCwianRpIjoiMzZmMDU5NDAtMGQzOC00MTFhLTg5MDktM2FlYTU4YmMxZjA5In0=.ea948e346d0683803aa4a2c09441bcbf7c79bd9234bed2ce8456ab3af257ea9f",
        "expires": 1510684200
    }
}
```

## `POST` Generate a token

### Using a username and password

```http
https://useast.api.elasticpath.com/v2/customers/tokens
```

#### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

#### Body

| Name                       | Required | Type     | Description               |
|:---------------------------|:---------|:---------|:--------------------------|
| `password`                 | Required | `string` | The customer password.    |
| `email`                    | Required | `string` | The customer email.       |
| `type`                     | Required | `string` | This must be `token`.     |
| `authentication_mechanism` | Optional | `string` | For password login this value should be `password`. |

### Username and Password Request Example

#### Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/customers/tokens \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
        "data":{
          "type": "token",
          "email": "ron@swanson.com",
          "password": "mysecretpassword",
          "authentication_mechanism": "password"
        }
     }
```

#### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
});
const email = "ron@swanson.com";
const password = "mysecretpassword";
Moltin.Customers.TokenViaPassword(email, password).then((data) => {
    // Do something
});
```

### Response example

`200 OK`

```json
{
    "data": {
        "type": "token",
        "id": "36f05940-0d38-411a-8909-3aea58bc1f09",
        "customer_id": "79cc0486-bbdf-491b-a0a2-722383b6288b",
        "token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiI3OWNjMDQ4Ni1iYmRmLTQ5MWItYTBhMi03MjIzODNiNjI4OGIiLCJuYW1lIjoiUm9uIFN3YW5zb24iLCJleHAiOjE1MTA2ODQyMDAsImlhdCI6MTUxMDU5NzgwMCwianRpIjoiMzZmMDU5NDAtMGQzOC00MTFhLTg5MDktM2FlYTU4YmMxZjA5In0=.ea948e346d0683803aa4a2c09441bcbf7c79bd9234bed2ce8456ab3af257ea9f",
        "expires": 1510684200
    }
}
```

## Using OpenID Connect

For more information on requesting a customer token with OpenID Connect, refer to the Developer How-To: [Single sign-on with OpenID Connect](/guides/How-To/Authentication/get-single-sign-on-account-management-token).

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name                       | Required | Type     | Description               |
|:---------------------------|:---------|:---------|:--------------------------|
| `type`                     | Required | `string` | This must be `token`.     |
| `authentication_mechanism` | Required | `string` | For OpenID Connect login this value should be `oidc`. |
| `oauth_authorization_code` | Required | `string` | The code returned from the OpenID Connect Provider authentication. |
| `oauth_redirect_uri`       | Required | `string` | The url of the front-end that handles the callback of the token. |
| `oauth_code_verifier`      | Required | `string` | The Proof Key for Code Exchange (PKCE) Code Verifier, corresponding to the Code Challenge that was supplied to the Authorization endpoint. See [Generating a Code Verifier and Challenge](/guides/How-To/Authentication/get-single-sign-on-account-management-token#generate-proof-key-for-code-exchange-parameters). |

## Open ID Connect Request Example

### Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/customers/tokens \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
        "data":{
          "type": "token",
          "authentication_mechanism": "oidc",
          "oauth_authorization_code":  "c2490f06-6d8e-4927-99aa-4bf02b419e96",
          "oauth_redirect_uri": "https://example-store.com/oauth2/callback",
          "oauth_code_verifier": "0E934PurR8ExVg6Pj7T4kQewxKzWSfSFG5d15FGfww8"
        }
     }'
```

### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
});
const code = "XXXX";
const redirectUri = "XXXX";
const codeVerifier = "XXXX";

Moltin.Customers.TokenViaOIDC(code, redirectUri, codeVerifier).then((data) => {
    // Do something
});
```

### Response example

`200 OK`

```json
{
    "data": {
        "type": "token",
        "id": "5266d6da-a5e2-4f79-9e8c-6d050ffe7fee",
        "customer_id": "be076eb9-689e-4cfe-8299-8489f99a14e6",
        "token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiJiZTA3NmViOS02ODllLTRjZmUtODI5OS04NDg5Zjk5YTE0ZTYiLCJuYW1lIjoiUm9uIFN3YW5zb24rNSIsImV4cCI6MTYwNTM4NDMxOSwiaWF0IjoxNjA1Mjk3OTE5LCJqdGkiOiI1MjY2ZDZkYS1hNWUyLTRmNzktOWU4Yy02ZDA1MGZmZTdmZWUifQ==.2af503b27022df40c769ac49d85802d0319d7ed14547c843c254d73f8107d8cd",
        "expires": 1605384319
    }
}
```

## Using a token

You can use a `X-Moltin-Customer-Token` header with the following endpoints. They’re available implicitly for you to read, create, and update various resources.

- [Get a Customer](/docs/customer-management/customer-management-api/get-a-customer)
- [Update a Customer](/docs/customer-management/customer-management-api/update-a-customer)
- [Get Customer Addresses](/docs/api/customer-addresses/get-v-2-customer-addresses)
- [Get an Address](/docs/api/customer-addresses/get-v-2-customer-addresses)
- [Create an Address](/docs/api/customer-addresses/post-v-2-customer-address)
- [Update an Address](/docs/api/customer-addresses/put-v-2-customer-address)
- [Get all Orders](/docs/api/carts/get-customer-orders)
- [Get an Order](/docs/api/carts/get-an-order)
- [Get Customer Carts](/docs/api/carts/get-a-cart)
- [Create an Association between a Customer and a Cart](/docs/api/carts/create-customer-cart-association)
- [Delete an Association Between a Customer and a Cart](/docs/api/carts/delete-customer-cart-association)

---

## Delete a Customer

## `DELETE` Delete by ID

```http
https://useast.api.elasticpath.com/v2/customers/:id
```

Deletes a customer by ID.

## Parameters

### Path parameters

| Name | Required | Type     | Description                        |
| ---- | -------- | -------- | ---------------------------------- |
| `id` | Required | `string` | The ID for the Customer to delete. |

### Headers

| Name                      | Required | Type     | Description                                                                                                                    |
| ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `X-Moltin-Customer-Token` | Optional | `string` | A customer token used to access customer implicitly.                                                                           |
| `Authorization`           | Required | `string` | The Bearer token required to get access to the API. If there is no customer token the grant type must be `client_credentials`. |

## Request Example Delete by ID

### Curl

```bash
curl -X DELETE https://useast.api.elasticpath.com/v2/customers/:id \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
    client_secret: "X",
});
const id = "XXXX";
Moltin.Customers.Delete(id).then((response) => {
    // Do something
});
```

## Request Example Delete With Customer Token

```bash
curl -X DELETE https://useast.api.elasticpath.com/v2/customers/:id \
     -H "X-Moltin-Customer-Token: XXXX"
     -H "Authorization: Bearer XXXX"
```

## Request Example Delete Without Customer Token

```bash
curl -X DELETE https://useast.api.elasticpath.com/v2/customers/:id \
     -H "Authorization: Bearer XXXX"
```

## Response Example

`204 No Content`

---

## Get a Customer

## `GET` Get by ID

```http
https://useast.api.elasticpath.com/v2/customers/:id
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                        |
| ---- | -------- | -------- | ---------------------------------- |
| `id` | Required | `string` | The ID for the requested Customer. |

### Headers

| Name                      | Required | Type     | Description                                                                                                                    |
| ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `X-Moltin-Customer-Token` | Optional | `string` | A customer token used to access a customer implicitly.                                                                         |
| `Authorization`           | Required | `string` | The Bearer token required to get access to the API. If there is no customer token the grant type must be `client_credentials`. |

## Request Example Without Customer Token

### Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/customers/:id \
     -H "Authorization: Bearer XXXX" \
     - -H "Content-Type: application/json" \
```

### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
    client_secret: "X",
});
const id = "XXXX";
Moltin.Customers.Get(id).then((customer) => {
    // Do something
});
```

## Request Example With Customer Token

### Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/customers/:id \
     -H "X-Moltin-Customer-Token: XXXX"
     -H "Authorization: Bearer XXXX"
```

### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
});
const customerId = "XXXX";
const customerToken = "XXXX";
Moltin.Customers.Get({
    id: customerId,
    token: customerToken,
}).then((customer) => {
    // Do something
});
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "customer",
        "id": "a23cc59d-a6c2-4c14-89c7-80fd7e4fc6c0",
        "name": "Ron Swanson",
        "email": "ronwanson@example.com",
        "external_ref": "16bedceb-8b2d-4f82-a973-b0a8d8432708",
        "password": true,
        "meta": {
            "timestamps": {
                "created_at": "2017-01-11T18:44:45Z",
                "updated_at": "2017-05-31T04:12:12Z"
            }
        }
    }
}
```

---

## Get all Customers

## `GET` Get a list of all customers

```http
https://useast.api.elasticpath.com/v2/customers
```

## Parameters

### Headers

| Name            | Required | Type     | Description                                                                                  |
| --------------- | -------- | -------- | -------------------------------------------------------------------------------------------- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. Grant type must be `client_credentials`. |

### Query parameters

| Name     | Required | Type     | Description                                                                              |
| -------- | -------- | -------- | ---------------------------------------------------------------------------------------- |
| `filter` | Optional | `string` | Filter the results. For more information, see [Filtering customers](#filtering). |
| `page[limit]`  | Optional | `integer` | The number of records per page.                 |
| `page[offset]` | Optional | `integer` | The number of records to offset the results by. |
| `page[total_method]` | Optional | `string` | One of `exact` or `observed`, controls how the [total number of results are calculated](/guides/Getting-Started/pagination#total-method-calculation) |
| `sort`   | Optional | `string` | Specifies the attribute to sort by. Supported attributes are `created_at`,`email`,`id`,`name`,`updated_at`. By default, sort order is ascending. To sort in descending order, prefix the attribute with `-`, for example, `-updated_at`. The default value is `created_at` in descending order. For more information, see [Sorting](/guides/Getting-Started/sorting). |

:::note
You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).
:::

## Filtering

The following table describes the supported operator and attributes when [filtering](/guides/Getting-Started/filtering) customers.

| Attribute | Type | Operators | Example |
| --- | --- | --- | --- |
| `email` | `string` | `eq``like` | `eq(email,ronswanson@example.com)` |
| `name` | `string` | `eq``like` | `like(name,*swan*)` |
|  `id` | `string` | `eq``ge``gt``le``lt` | `eq(id,787af9a4-83e1-4216-bc60-df076daef0c5)` |
|  `created_at` | `string` |  `eq``ge``gt``le``lt` | `gt(created_at,"2021-06-02T18:44:07.617Z")` |
| `updated_at` | `string` |  `eq``ge``gt``le``lt` | `ge(updated_at,"2021-06-07T18:24:48.149Z")` |
| `external_ref` | `string` |  `eq` | `eq(external_ref,"16bedceb-8b2d-4f82-a973-b0a8d8432708")` |

## Request Examples

### Curl

```bash
curl -X GET https://useast.api.elasticpath.com/v2/customers \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
});
Moltin.Customers.All().then((customer) => {
    // Do something
});
//Filter example
Moltin.Customers.Filter({ eq: { email: "jim@bob.com" } })
    .All()
    .then((customers) => {
        // Do something
    });
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "type": "customer",
            "id": "2479c9b3-615d-4ebc-a99d-87ffc67d1955",
            "name": "Ron Swanson",
            "email": "ron@swanson.com",
            "password": true,
            "meta": {
                "timestamps": {
                    "created_at": "2017-01-11T18:44:45Z",
                    "updated_at": "2017-05-31T04:12:12Z"
                }
            }
        },
        {
            "type": "customer",
            "id": "7746d533-fd64-446f-ae8c-f8e07f3ed9fd",
            "name": "Ron Swanson_",
            "email": "ron_@swanson.com",
            "external_ref": "16bedceb-8b2d-4f82-a973-b0a8d8432708",
            "password": true,
            "meta": {
                "timestamps": {
                    "created_at": "2017-02-20T17:31:45Z",
                    "updated_at": "2017-04-14T18:55:59Z"
                }
            }
        }
    ],
    "meta": {
        "page": {
            "limit": 10,
            "offset": 0,
            "current": 1,
            "total": 1
        },
        "results": {
            "total": 2,
            "total_method": "exact"
        }
    }
}
```

---

## Update a Customer

## `PUT` Update by ID

```http
https://useast.api.elasticpath.com/v2/customers/:customerId
```

## Parameters

### Path parameters

| Name         | Required | Type     | Description                        |
| ------------ | -------- | -------- | ---------------------------------- |
| `customerId` | Required | `string` | The ID for the customer requested. |

### Headers

| Name                      | Required | Type     | Description                                                                                                                    |
| ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `X-Moltin-Customer-Token` | Optional | `string` | A customer token used to access customer implicitly.                                                                           |
| `Authorization`           | Required | `string` | The Bearer token required to get access to the API. If there is no customer token the grant type must be `client_credentials.` |

### Body

| Name           | Required | Type     | Description                                                                                                                                                                |
|----------------| -------- | -------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type`         | Required | `string` | The type of object being returned.                                                                                                                                         |
| `name`         | Optional | `string` | The full name of the customer.                                                                                                                                             |
| `email`        | Optional | `string` | The customer email.                                                                                                                                                        |
| `password`     | Optional | `string` | The customer password.                                                                                                                                                     |
| `external_ref` | Optional | `string` | The unique attribute associated with the customer. For example, this could be an external reference from a separate company system. The maximum length is 2048 characters. Default is `null`. |

## Request Examples

### Curl

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/customers/:customerId \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $ {
     "data": {
       "type": "customer",
       "email": "ron@swanson.com"
     }
}
```

### JavaScript SDK

```javascript
const MoltinGateway = require("@moltin/sdk").gateway;
const Moltin = MoltinGateway({
    client_id: "X",
});
var customerId = "XXXX";
var customer = {
    email: "ron@swanson.com",
};
Moltin.Customers.Update(customerId, customer).then((response) => {
    // Do something
});
```

## Request Example With Customer Token

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/customers/:id \
     -H "X-Moltin-Customer-Token: XXXX"
     -H "Authorization: Bearer XXXX"
     -d $'{
     "data": {
       "type": "customer",
       "email": "ron@swanson.com"
     }
}'
```

## Request Example Without Customer Token

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/customers/:id \
     -H "Authorization: Bearer XXXX"
     -d $'{
     "data": {
       "type": "customer",
       "email": "ron@swanson.com"
     }
}'
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "customer",
        "id": "b57022cf-c80e-4b85-9fd1-5af3156d8adf",
        "name": "George example",
        "email": "ron@swanson.com",
        "password": true,
        "meta": {
            "timestamps": {
                "created_at": "2017-01-11T18:44:45Z",
                "updated_at": "2017-05-31T04:12:12Z"
            }
        }
    }
}
```

---

## Overview(Customer-management)

Customers are the people who purchase products from your store. In a business-to-consumer store, a customer is a shopper who buys products for their personal use. In a business-to-business store, a customer is a buyer who purchases products on behalf of their organization.

When a customer is ready to purchase for the first time, the customer creates a profile. At a minimum, the customer provides personal contact information, such as full name, telephone numbers, and addresses. As a store administrator, you can extend the types of information that you want to collect about customers. For example, if the customer is a buyer, you might also collect information about their organization and preferred method of payment.

As a customer uses your store, you can enhance the customer profile with relationships to other information, such as payment methods, promotions, and order history.

:::note
[Accounts](/docs/api/accounts/account-management-introduction#accounts-vs-customers) represent the next generation of Customers. While Customers are essential, Accounts offer enhanced capabilities. We recommend using Accounts for any of your new use cases.
:::

:::tip
To enable customers to create and manage their own profiles, implement customer tokens. Tokens are encrypted to protect usernames and passwords.
:::

---

## Commands

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Composable CLI commands for storefront development

This reference lists the commands that you can use to build storefronts with Composable CLI.

## Command Overview

Composable CLI accelerates your time to market by providing the following features:

- Create new Next.js storefronts
- Easy setup and configuration of Elastic Path Products and Integrations

---

## Command Syntax

If you've installed Composable CLI globally you can run all commands using your package manager:

<Tabs>
<TabItem value="alias" label="Alias">

```bash
ep [COMMAND] --[FLAG]
```

</TabItem>
<TabItem value="standard" label="Standard">

```bash
composable-cli [COMMAND] --[FLAG]
```

</TabItem>
</Tabs>

---

## Command reference

| **Command** | **Alias** |                                     **Description** |
|:------------|:-----:|--------------------------------------------------------:|
| login       |       |                             Login to the Composable CLI |
| logout      |       |                            Logout of the Composable CLI |
| feedback    |       |                          Feedback to the Composable CLI |
| config      |       |                      interact with stored configuration |
| store       |       |                         interact with Elastic Path store |
| generate    |   g   |                         generate Elastic Path storefront |
| insights    |       |                             opt in/out product insights |
| integration |  int  |     Setup Elastic Path integrations for your storefront |
| payments    |   p   | Setup Elastic Path payment gateways for your storefront |

| **Options**    | **Description**                                     | **Value**                  |
|:---------------|:----------------------------------------------------|---------------------------:|
| --version      | Show version number                                 | [boolean]                  |
| --debug      | Debug mode. This is true by default if the collection is a relative path | [boolean] [default: null] |
| --interactive  | Setting to false disables interactive input prompts.| [boolean] [default: true]  |
| -v, --verbose  | Run with verbose logging                            | [boolean] [default: false] |
| -dry-run       | Run without generating output                       | [boolean] [default: null]  |
| -allow-private | Allow private schematics to be run from the command line. | [boolean] [default: false] |
| --force        | Force overwriting files that would otherwise be an error. | [boolean] |
| --list-schematics | List all schematics from the collection, by name. | [boolean]                 |
| -h, --help          | Show help                                       | [boolean]                 |

---

## login

Authenticate to the Composable CLI

```bash
ep login
```

### Flags

| Flag         |          Description           |
|:-------------|:------------------------------:|
| --region, -r | Region of Elastic Path account |

---

## Logout

Logout of the Composable CLI

```bash
ep logout
```

---

:::note
D2C is the only available option at this time
:::

## Generate

Generate a new Elastic Path storefront

```bash
ep generate d2c [project-name]
```

### Flags

| Flag               |            Description             |
|:-------------------|:----------------------------------:|
| --project-name, -p |    The name of the new project.    |
| --help, -h         | Show help for the generate command |

---

:::caution
Work in progress more coming soon
:::

---

## Installation and Setup

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import {
    NextjsPlain,
    NodejsOriginal,
    GitOriginal,
    NpmOriginalWordmark,
    YarnOriginal,
    PnpmOriginal,
} from 'devicons-react';

# Composable CLI for frontend experiences

The Composable CLI is a command line tool designed to make it easy for you to build Elastic Path-powered frontend experiences. It also enables you to configure various products and integrations provided by Elastic Path.

You need to use Node.js to install Composable CLI and manage its dependencies.

This documentation explains how to use Composable CLI for developing storefronts.
## Features

Composable CLI accelerates your time to market by providing the following features:

- Create new <NextjsPlain/> Next.js storefronts
- Easy setup and configuration of Elastic Path Products and Integrations

## Prerequisites

- <NodejsOriginal/> Node.js v18 or later
- You've installed a <NodejsOriginal/> Node.js package manager: either <NpmOriginalWordmark/> [npm](https://www.npmjs.com/get-npm), <YarnOriginal/> [Yarn 1.x](https://classic.yarnpkg.com/lang/en/docs/install), or <PnpmOriginal/> [pnpm](https://pnpm.io/installation).
- You've installed <GitOriginal/> [Git](https://git-scm.com/)

## Installation

Composable CLI is available as an npm package: [composable-cli](https://www.npmjs.com/package/composable-cli).

In your terminal, run the following command to install Composable CLI:

<Tabs>

<TabItem title="npm" value={"npm"}>

```bash
npm install -g composable-cli
```

</TabItem>

<TabItem title="pnpm" value={"pnpm"}>

```bash
pnpm add -g composable-cli
```

</TabItem>

<TabItem title="yarn" value={"yarn"}>

```bash
yarn global add composable-cli
```

</TabItem>

</Tabs>

You can verify that Composable CLI is installed correctly by running the following command:

```bash
ep --version
```

Composable CLI can execute commands using either it primary command `composable-cli` or its alias `ep`.

## Authentication

To use Composable CLI, you need to authenticate with Elastic Path. You can do this by running the following command:

```bash
ep login
```

This command will prompt you for your username and password. After you authenticate, Composable CLI will keep you signed in. If you wish to sign out, you can run the following command:

```bash
ep logout
```

---

## Deployment on Vercel

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Deploying your storefront on Vercel

The storefront generated by Composable CLI is ready to deploy to any Next.js supporting hosting provider.

The following is a quick guide to deploying the Composable Starter to Vercel using the Vercel CLI. For more detailed information about features and additional functionality, see the [Vercel documentation](https://vercel.com/docs/cli).

## Pre-requisites

### Generated storefront

You will need to have generated a storefront using the Composable CLI. If you haven't done this yet, you can follow the [getting started guide](/docs/developer-tools/composable-starter/storefront-starter) to generate a storefront.

### Required Accounts

- [Vercel Account](https://vercel.com/signup)
- [GitHub Account](https://github.com/signup): only required if you want to use GitHub continuous deployment

### Required tooling
- [Git and Git CLI](https://git-scm.com/): only required if you want to use GitHub continuous deployment

## Deployment Options

Once you have a Vercel account, you can deploy your storefront by using the Vercel CLI or GitHub and Vercel continuous deployment see the instruction below.

- [Deploying to Vercel using GitHub continuous deployment](#option-1-deploying-to-vercel-using-github-continuous-deployment)
- [Deploying to Vercel using the Vercel CLI](#option-2-deploying-to-vercel-using-the-vercel-cli)

## Option 1: Deploying to Vercel using GitHub continuous deployment

The following is a quick guide to deploying the Composable Starter to Vercel using GitHub.

### Create a GitHub repository

Before you can deploy, you need to create a GitHub repository and push the starter codebase to it:

1. On GitHub, click the plus icon at the top right, then click New Repository.
2. You’ll then be redirected to a new page with a form. In the form, enter the Repository Name.
3. Scroll down and click Create repository.

more information about creating a GitHub repository can be found [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories).

#### Push the starter codebase to GitHub

Now that you have an empty repository the next step is to push the starter codebase to GitHub.

Looking at the repository page on GitHub you should see a URL that you can copy to connect to the repository e.g. `https://github.com/<your-account>/<your-repo>.git`

A local repository should have been initialized when you generated your storefront. If not, you can initialize a local repository by running the following command in the root of your storefront directory:

```bash
git init
git add .
git commit -m "initial commit"
```

Now in your terminal run the following command to connect your local repository to the GitHub repository you just created:

```bash
git remote add origin https://github.com/<your-account>/<your-repo>.git
```

making sure to replace `https://github.com/<your-account>/<your-repo>.git` with your repository URL.

Finally, push the starter codebase to GitHub by running the following command:

```bash
git push origin main
```

After the push is complete, you should see the starter codebase in your GitHub repository.

### Deploy using Vercel Dashboard

1. Login to your Vercel account and load the [dashboard](https://vercel.com/dashboard).
2. Click on "Add new..."
3. Choose project from the dropdown
4. In the Import page that opens, find the Git repository you just created and click Import. Make sure you have connected Vercel to your GitHub account first.
5. In the Configure Project form:
    - Optionally change the projects name.
    - Open the "Environment Variables" section:
         - Add the environment variables to match your local environment. You can find these in the `.env.local` file in the root of your storefront directory. e.g. `NEXT_PUBLIC_EPCC_CLIENT_ID`, `NEXT_PUBLIC_PASSWORD_PROFILE_ID` etc
         - Instead of entering them individually, you can copy the contents of the file and paste it into the "Key" input on the form for all values to populate.
6. Once all the settings are correct, click Deploy.

This will start the deployment of the Composable Starter. Once it’s done, you’ll be redirected to the main dashboard of your new project.

## Option 2: Deploying to Vercel using the Vercel CLI

### Install the Vercel CLI

To install the Vercel CLI globally, run the following command:

<Tabs>
<TabItem title="npm" value="npm" default>

```bash
npm i -g vercel
```

</TabItem>
<TabItem title="pnpm" value="pnpm">

```bash
pnpm i -g vercel
```

</TabItem>
<TabItem title="yarn" value="yarn">

```bash
yarn global add vercel
```

</TabItem>
</Tabs>

You can confirm it installed correctly by running:

```bash
vercel --version
```

this should output something like below but with your installed version:

```bash
Vercel CLI 29.0.0
29.0.0
```

### Create and link a project

Vercel projects are the top level container for your deployments. To link our storefront folder with a new project, run the following command in your storefront directory:

```bash
vercel link
```

Follow the prompts to link and create the project. Making sure to answer the questions as follows:

```bash
? Set up “~/my-storefront”? [Y/n] y
? Which scope should contain your project? my-account (your account name)
? Link to an existing project? [Y/n] n
? What’s your project’s name? my-storefront (the name you want for the vercel project)
? In which directory is your code located? ./
Local settings detected in vercel.json:
Auto-detected Project Settings (Next.js):
- Build Command: next build
- Development Command: next dev --port $PORT
- Install Command: `yarn install`, `pnpm install`, `npm install`, or `bun install`
- Output Directory: Next.js default
? Want to modify these settings? [y/N] n
✅  Linked to my-account/my-storefront (created .vercel)
```

You should get a message to confirm the project has been linked. If there is any issues getting the project linked you can have a look at the [Vercel CLI docs](https://vercel.com/docs/cli/link).

The **most important outcome** is the auto-detected project settings. This should have been Next.js if it wasn't you will have to open the [project settings](https://vercel.com/docs/projects/overview#build-and-development-settings) in the vercel dashboard and set the "Framework Preset" dropdown to Next.js or manually set the values for Build command, Development command, Install command and Output directory to match the above setup.

### Setting environment variables

The project needs to have the appropriate environment variables set to be able to deploy your storefront. There are different ways to set environment variables in Vercel projects:

- [Using the Vercel dashboard (recommended)](#using-the-vercel-dashboard)
- [Using the Vercel CLI](#using-the-vercel-dashboard)

:::note
The environment variables you need to match your local environment in Vercel are located in the `.env.local` file in the root of your storefront directory.
:::

#### Using the Vercel dashboard

Follow the instructions in the [Vercel docs](https://vercel.com/docs/projects/environment-variables#declare-an-environment-variable) to add the following environment variables from your `.env.local` to your project.

#### Using the Vercel CLI

:::caution
At this time there is no built-in way to add multiple environment variables at once using the Vercel CLI see [this issue](https://github.com/vercel/vercel/discussions/4977). You can use the [Vercel dashboard](https://vercel.com/dashboard) to add multiple environment variables at once.
:::

To set environment variables using the Vercel CLI, run the following command:

```bash
vercel env add NEXT_PUBLIC_EPCC_CLIENT_ID
```

where `NEXT_PUBLIC_EPCC_CLIENT_ID` is the name of the environment variable you want to set. You will be prompted to enter the value for the environment variable and what environments you want to set it for.

Frustratingly it's not currently possible to set multiple environment variables at once using the Vercel CLI. The above process will have to be repeated for each environment variable that we have to set. Alternatively you can use the [Vercel dashboard](https://vercel.com/dashboard) to add multiple environment variables at once.

### Deploy storefront to Vercel

Lastly we need to deploy the storefront to Vercel. To do this run the following command in your storefront directory:

```bash
  vercel deploy
```

The storefront will be built and deployed to Vercel. Once the deployment is complete you will be given a URL to access your storefront.

more information can be found from the [Vercel cli docs](https://vercel.com/docs/cli/deploying-from-cli)

---

## Getting Started

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Getting started with Composable Starter

Composable Starter is the toolkit recommended by Elastic Path for creating headless commerce storefronts. It includes a set of practical components, tools, and utilities that reflect Elastic Path's best practices for building custom web storefronts.

## What you’ll build

You’re going to complete the following tasks:

- Creating a new Composable Starter (Next.js) app using the Composable CLI
- Running your storefront in your local development environment
- Setting up continuous deployment with GitHub and Vercel
- Deploying your app to production

## Prerequisites

- Node.js v18 or later
- You've installed a Node.js package manager: either [npm](https://www.npmjs.com/get-npm), [Yarn 1.x](https://classic.yarnpkg.com/lang/en/docs/install), or [pnpm](https://pnpm.io/installation).
- You've installed [Git](https://git-scm.com/)

### Elastic Path account
You'll also need an Elastic Path account to access the backend. If you don't have one, you can [sign up for a free trial](https://useast.cm.elasticpath.com/free-trial).

### Install Composable CLI globally and authenticate

You'll need to install the latest version of composable-cli to get started. You can do this by running the following command:

<Tabs>

<TabItem value="npm" title="npm" default>

```bash
npm install -g composable-cli
```

</TabItem>
<TabItem title="pnpm" value="pnpm" >

```bash
pnpm install -g composable-cli
```

</TabItem>

<TabItem title="yarn" value="yarn">

```bash
yarn global add composable-cli
```

</TabItem>
</Tabs>

Then authenticate with Elastic Path by running the following command:

```bash
ep login
```

For further explanation see [Authentication](/docs/developer-tools/composable-cli/installation#authentication).

## Create a new Composable Starter app

In your terminal, run the following command to create a new Composable Starter app:

```bash
ep generate my-storefront
```

where `my-storefront` is the name you want to call your storefront project.

### Select a store

If you've not selected a store yet, you'll be prompted to select a store from a list of stores that you have access to.

Select the store you want to use for your storefront. If you've already selected a store you will see the "Using store" info message that tells you what store is active. You can switch store by calling the `ep store set` command [learn more here](/docs/developer-tools/composable-cli/commands#command-reference)

### Select configuration

The Composable CLI will prompt you to select from different configurations.

- PLP (Product List Page) type - storefront page that presents a list of products based on a category or search query
- Payment Gateway - the payment processor that will handle checkout in the storefront

For this tutorial, select the following options:

- PLP type: `Simple`
- Payment Gateway: `Simple (quick start)`

Once you've selected your configuration, the Composable CLI will create a new directory with the name you provided, scaffold out your new storefront project and perform configurations based on the options you selected.

## Running the storefront locally

The Composable Starter app is built on top of [Next.js](https://nextjs.org/). Your local developer experience will be the same as any Next.js app. To learn more about Next.js, see the [Next.js documentation](https://nextjs.org/docs).

If it's the first time your running a composable starter project, don't forget to **install your dependencies** by running the following command **from your project directory**:

<Tabs>

<TabItem title="npm" value={"npm"} default>

```bash
npm install
```

</TabItem>
<TabItem title="pnpm" value={"pnpm"}>

```bash
pnpm install
```

</TabItem>
<TabItem title="yarn" value={"yarn"}>

```bash
yarn install
```

</TabItem>
</Tabs>

To run your storefront locally, run the following command **from your project directory**:

<Tabs>

<TabItem title="npm" value={"npm"}>

```bash
npm run dev
```

</TabItem>

<TabItem title="pnpm" value={"pnpm"}>

```bash
pnpm dev
```

</TabItem>

<TabItem title="yarn" value={"yarn"}>

```bash
yarn dev
```

</TabItem>

</Tabs>

Your Next.js Elastic Path powered storefront will run at `` (look at the terminal output for the exact URL as your local environment may be different).

## Deploying your storefront

Lean how to deploy your storefront to production [here](/docs/developer-tools/composable-starter/deploy/storefront-deploy).

---

## Troubleshooting

## Error: Invalid src prop ... on `next/image`, hostname is not configured under images in your `next.config.js`

We are using next/image to optimize images for your storefront. A common reason for this error is you have added images with "External URLs" in Product Experience Manager. To fix this, you need to add the domain to the `next.config.js` file.

```javascript
module.exports = {
  images: {
    domains: ['cdn.example.com'],
  },
}
```

## Failed configuration tasks
One of my configuration tasks failed. What should I do?

If one or more of your configuration tasks failed you can retry them by running the appropriate CLI command from your project directory:

e.g. Algolia configuration:

```bash
ep int algolia
```

e.g. Elastic Path Payments configuration:

```bash
ep payments ep-payments
```

full list of available configuration tasks can be found in the [Composable CLI docs](/docs/developer-tools/composable-cli/commands).

---

## Storefront: Environment Setup

## Understanding the .env.local file

:::info
Coming soon
:::

---

## Storefront: Use application keys

## Using the application key in storefront

### Behavior without a key

If you don't pass a client id and/or client secret you will get a 401 error when trying to access the API.

### Using the JS SDK

If you are using the JS SDK you can pass the client id and client secret to the `createClient` function.

```typescript
import { gateway } from "@moltin/sdk"

gateway({
  client_id: "xyz8hblk8yfWtPi0vVCHbIxkb3dtvNYWY1Rxvih2nR",
  host: "useast.api.elasticpath.com",
  ...
});
```

The JS SDK will use the client id to generate an access token that will be set in the `Authorization` header of all requests as a `Bearer` token. e.g. `Authorization: Bearer xyz8hblk8yfWtPi0vVCHbIxkb3dtvNYWY1Rxvih2nR`

### Using Elastic Path React Hooks

You can pass the client id and host to the ElasticPathProvider component.

```tsx
function App() {
  return (
    <ElasticPathProvider
      queryClientProviderProps={{ client: queryClient }}
      host="useast.api.elasticpath.com"
      clientId="xyz8hblk8yfWtPi0vVCHbIxkb3dtvNYWY1Rxvih2nR"
      ...
    >
      ...
    </ElasticPathProvider>
  )
}
```

You can also pass a JS SDK client directly to the ElasticPathProvider component.

```tsx
function App() {
  return (
    <ElasticPathProvider
      queryClientProviderProps={{ client: queryClient }}
      client={client}
    >
      ...
    </ElasticPathProvider>
  )
}
```

### Using fetch directly

If you are using fetch directly you'll have to do the request for an access token yourself and manage it's persistence.

#### Request for an access token using client id

```typescript
fetch("https://useast.api.elasticpath.com/oauth/access_token", {
    method: "POST",
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: Object.keys({
      client_id: "xyz8hblk8yfWtPi0vVCHbIxkb3dtvNYWY1Rxvih2nR",
      grant_type: "implicit"
    })
      .map(k => `${encodeURIComponent(k)}=${encodeURIComponent(body[k])}`)
      .join('&')
}).then(response => response.json())
  .then(data => console.log(data));
```

#### Using access token in api fetch requests

```typescript
fetch("https://useast.api.elasticpath.com/catalog/products", {
    headers: {
      'Authorization': 'Bearer 12348dcd5ed48bbdbaf8bb2b029a9682cd8e5689'
    }
}).then(response => response.json())
  .then(data => console.log(data));
```

---

## Logout

## Why proper logout matters 🔒

A secure logout process is essential for protecting user data, especially on shared devices. This guide shows how to properly terminate sessions by clearing tokens and optionally revoking them server-side.

:::tip
Make sure you've completed the [Quick Start](../quickstart) and understand [Token Management](./token-management) before implementing logout functionality.
:::

---

## 1 · Client-side logout (clearing tokens)

The new SDK provides built-in methods for clearing authentication state. When implementing logout, the Account Management token is the primary security concern since it identifies the specific user.

### Using the SDK's auth methods

```tsx
import React from "react";
import { useNavigate } from "react-router-dom";
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  { clientId: process.env.NEXT_PUBLIC_CLIENT_ID }
);

const LogoutButton: React.FC = () => {
  const navigate = useNavigate();

  const handleLogout = async () => {
    // Clear authentication using SDK
    await auth.clear();
    
    // Also clear account tokens (not managed by SDK)
    localStorage.removeItem("ep_account_token");
    localStorage.removeItem("ep_account_refresh_token");

    // Redirect to login page
    navigate("/login");
  };

  return (
    <button onClick={handleLogout} className="logout-button">
      Sign Out
    </button>
  );
};

export default LogoutButton;
```

### Manual token clearing

If you need more control:

```tsx
import React from "react";
import { useNavigate } from "react-router-dom";

const ManualLogoutButton: React.FC = () => {
  const navigate = useNavigate();

  const handleLogout = () => {
    // Clear all authentication tokens
    const authKeys = [
      "ep_implicit_token",
      "ep_account_token", 
      "ep_account_refresh_token",
      "_store_ep_credentials" // SDK's default storage key
    ];
    
    authKeys.forEach(key => localStorage.removeItem(key));

    // Redirect to login page
    navigate("/login");
  };

  return (
    <button onClick={handleLogout} className="logout-button">
      Sign Out
    </button>
  );
};
```

### Cookie-based storage logout

When using cookies with the SDK:

```tsx
import React from "react";
import { useNavigate } from "react-router-dom";
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

// Configure client with cookie storage
const { auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  { 
    clientId: process.env.NEXT_PUBLIC_CLIENT_ID,
    storage: "cookie"
  }
);

const CookieLogoutButton: React.FC = () => {
  const navigate = useNavigate();

  const handleLogout = async () => {
    // SDK clears its own cookies
    await auth.clear();
    
    // Clear any additional cookies
    document.cookie =
      "ep_account_token=; Path=/; Expires=Thu, 01 Jan 1970 00:00:01 GMT;";
    document.cookie =
      "ep_account_refresh_token=; Path=/; Expires=Thu, 01 Jan 1970 00:00:01 GMT;";

    // Redirect to login page
    navigate("/login");
  };

  return <button onClick={handleLogout}>Sign Out</button>;
};

export default CookieLogoutButton;
```

## 2 · Server-side logout (for HttpOnly cookies)

For maximum security with SSR applications:

```tsx
// Client-side React component
import React from "react";
import { useNavigate } from "react-router-dom";

const ServerLogoutButton: React.FC = () => {
  const navigate = useNavigate();
  const [isLoggingOut, setIsLoggingOut] = React.useState(false);

  const handleLogout = async () => {
    setIsLoggingOut(true);

    try {
      // Call your backend logout endpoint
      await fetch("/api/logout", {
        method: "POST",
        credentials: "include", // Important to include cookies
      });

      // Redirect to login page after server confirms logout
      navigate("/login");
    } catch (error) {
      console.error("Logout failed:", error);
      // Fallback: redirect anyway
      navigate("/login");
    } finally {
      setIsLoggingOut(false);
    }
  };

  return (
    <button onClick={handleLogout} disabled={isLoggingOut}>
      {isLoggingOut ? "Signing out..." : "Sign Out"}
    </button>
  );
};

export default ServerLogoutButton;
```

### Server-side implementation (Next.js App Router example)

```ts
// app/api/logout/route.ts
import { cookies } from "next/headers";
import { NextResponse } from "next/server";

export async function POST() {
  const cookieStore = cookies();
  
  // Clear all auth cookies
  cookieStore.delete("ep_implicit_token");
  cookieStore.delete("ep_account_token");
  cookieStore.delete("ep_account_refresh_token");
  cookieStore.delete("_store_ep_credentials"); // SDK's cookie

  return NextResponse.json({ success: true });
}
```

:::info
**Note on token invalidation**

Elastic Path currently does not offer a direct API endpoint to revoke account tokens. The most secure approach is to:

1. Clear all tokens from client storage
2. For server-rendered applications, clear any session state on your server
3. For added security with HttpOnly cookies, set an immediate expiry on the server
   :::

## 3 · Handling logout across multiple tabs

The SDK automatically synchronizes authentication state across tabs when using localStorage. However, you may want to enhance the UI response:

While localStorage is shared across all tabs from the same domain (meaning tokens removed in one tab are removed everywhere), other tabs won't automatically detect this change and update their UI state unless specifically notified. Here's how to synchronize logout UI state across tabs:

```tsx
import React, { useEffect, useState } from "react";
import { useNavigate } from "react-router-dom";

const MultiTabLogoutButton: React.FC = () => {
  const navigate = useNavigate();
  const [isAuthenticated, setIsAuthenticated] = useState(true);

  // Listen for logout events from other tabs
  useEffect(() => {
    const checkAuth = () => {
      const accountToken = localStorage.getItem("ep_account_token");
      setIsAuthenticated(!!accountToken);

      // If no token found, redirect to login
      if (!accountToken && isAuthenticated) {
        navigate("/login");
      }
    };

    // Initial check
    checkAuth();

    // Event handler for storage changes
    const handleStorageChange = (event: StorageEvent) => {
      // When another tab triggers logout by setting this flag
      if (event.key === "ep_user_logged_out") {
        checkAuth();
      }
    };

    window.addEventListener("storage", handleStorageChange);

    return () => {
      window.removeEventListener("storage", handleStorageChange);
    };
  }, [navigate, isAuthenticated]);

  const handleLogout = () => {
    // Clear tokens (will affect all tabs)
    localStorage.removeItem("ep_account_token");
    localStorage.removeItem("ep_implicit_token");

    // Notify other tabs about logout
    localStorage.setItem("ep_user_logged_out", Date.now().toString());

    // Update local state and navigate
    setIsAuthenticated(false);
    navigate("/login");
  };

  return (
    <button onClick={handleLogout} disabled={!isAuthenticated}>
      Sign Out
    </button>
  );
};

export default MultiTabLogoutButton;
```

:::info
The key point here isn't about clearing the tokens (which are automatically shared), but rather notifying other tabs to update their UI state in response to the tokens being removed. This synchronization helps provide a consistent experience across all open tabs.
:::

## 4 · Automatically logging out inactive users

Combine the SDK's auth methods with activity monitoring:

For security-sensitive applications, you might want to automatically log out users after a period of inactivity:

```tsx
import React, { useEffect } from "react";
import { useNavigate } from "react-router-dom";
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const INACTIVITY_LIMIT = 30 * 60 * 1000; // 30 minutes

// Get auth instance
const { auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  { clientId: process.env.NEXT_PUBLIC_CLIENT_ID }
);

const InactivityMonitor: React.FC<{ children: React.ReactNode }> = ({
  children,
}) => {
  const navigate = useNavigate();

  useEffect(() => {
    let inactivityTimeout: number | undefined;

    // Function to logout and redirect
    const logout = async () => {
      // Use SDK to clear authentication
      await auth.clear();
      
      // Clear account tokens
      localStorage.removeItem("ep_account_token");
      localStorage.removeItem("ep_account_refresh_token");
      
      navigate("/login");
    };

    // Reset the timer on user activity
    const resetTimer = () => {
      if (inactivityTimeout) window.clearTimeout(inactivityTimeout);
      inactivityTimeout = window.setTimeout(logout, INACTIVITY_LIMIT);
    };

    // Monitor user activity
    const events = [
      "mousedown",
      "mousemove",
      "keypress",
      "scroll",
      "touchstart",
    ];

    events.forEach((event) => {
      document.addEventListener(event, resetTimer, true);
    });

    // Initial timer setup
    resetTimer();

    // Cleanup
    return () => {
      if (inactivityTimeout) window.clearTimeout(inactivityTimeout);
      events.forEach((event) => {
        document.removeEventListener(event, resetTimer, true);
      });
    };
  }, [navigate]);

  return <>{children}</>;
};

// Usage in your app
const App: React.FC = () => {
  return (
    <InactivityMonitor>
      <YourApp />
    </InactivityMonitor>
  );
};

export default App;
```

:::info
When considering which tokens to clear during logout, remember:

- **Account Management token** - This is the critical one that represents user identity and must always be cleared during logout
- **Implicit token** - This functions more like a public API key to access the store and could technically be preserved, but it's generally cleaner to clear it as well
  :::

## 5 · Comprehensive logout service

For applications that need centralized logout logic:

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

class LogoutService {
  private auth: any;
  
  constructor() {
    const { auth } = createShopperClient(
      { baseUrl: process.env.NEXT_PUBLIC_EPCC_BASE_URL },
      { clientId: process.env.NEXT_PUBLIC_CLIENT_ID }
    );
    this.auth = auth;
  }
  
  async logout() {
    try {
      // Clear SDK authentication
      await this.auth.clear();
      
      // Clear account tokens
      this.clearAccountTokens();
      
      // Clear any app-specific data
      this.clearAppData();
      
      // Notify other tabs
      this.notifyOtherTabs();
      
      return { success: true };
    } catch (error) {
      console.error("Logout error:", error);
      // Even on error, try to clear what we can
      this.clearAccountTokens();
      throw error;
    }
  }
  
  private clearAccountTokens() {
    const accountKeys = [
      "ep_account_token",
      "ep_account_refresh_token",
      "ep_user_id",
      "ep_user_email"
    ];
    accountKeys.forEach(key => localStorage.removeItem(key));
  }
  
  private clearAppData() {
    // Clear any app-specific data
    sessionStorage.clear();
  }
  
  private notifyOtherTabs() {
    // Use broadcast channel for cross-tab communication
    const channel = new BroadcastChannel("auth_channel");
    channel.postMessage({ type: "logout" });
    channel.close();
  }
}

// Export singleton instance
export const logoutService = new LogoutService();
```

## 6 · Best practices

- **Use SDK methods**: Leverage `auth.clear()` for proper cleanup
- **Clear all auth data**: Remember both implicit and account tokens
- **Provide visual feedback**: Show users that logout is in progress/complete
- **Handle errors gracefully**: Always attempt cleanup even if some steps fail
- **Consider security levels**: Use HttpOnly cookies for high-security applications
- **Test multi-tab behavior**: Ensure consistent logout across browser tabs

For complete implementations, check out the [authentication examples](https://github.com/elasticpath/composable-frontend/tree/main/examples) in the Composable Frontend repository.

---

## Password Reset

## Why password reset is essential 🔐

Users frequently forget their passwords, making a secure password reset flow a critical component of any authentication system. This guide shows how to implement password reset functionality using the Elastic Path Shopper SDK and One-Time Password Tokens.

:::tip
This guide assumes you've already set up authentication following the [Authentication Concepts](../overview) and [Quick Start](../quickstart) guides, including properly configuring the SDK client and token handling with interceptors for both implicit and account tokens.

For a complete working example, check out the [Shopper Accounts Authentication example](https://github.com/elasticpath/composable-frontend/tree/main/examples/shopper-accounts-authentication) in the Composable Frontend repository.
:::

---

## 1 · Prerequisites for password reset

Before implementing password reset, ensure you have:

1. **Account Authentication Settings**: The `account_member_self_management` setting should be set to `update_only` to allow users to reset their passwords.

2. **Password Profile Configuration**: Set `enable_one_time_password_token` to `true` in your Password Profile.

3. **Webhook Setup**: Create a webhook that observes the `one-time-password-token-request.created` event, which will be used to send the token to the user via email or other channels.

## 2 · Password reset flow overview

The standard password reset flow has three main steps:

1. User requests a password reset by providing their username (typically their email)
2. User receives a one-time password token via email
3. User exchanges this token for an Account Management Authentication Token and sets a new password

## 3 · Requesting a password reset

Create a form component to capture the user's email and request a password reset token:

```tsx
import React, { useState } from "react";
import { createOneTimePasswordTokenRequest } from "@epcc-sdk/sdks-shopper";

function RequestPasswordReset() {
  const [username, setUsername] = useState("");
  const [status, setStatus] = useState({ type: "", message: "" });
  const [loading, setLoading] = useState(false);

  // Get password profile ID from your configuration
  const passwordProfileId = process.env.NEXT_PUBLIC_PASSWORD_PROFILE_ID;

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    setStatus({ type: "", message: "" });

    try {
      // Request one-time password token
      await createOneTimePasswordTokenRequest({
        username, // The user's email or username
        password_profile_id: passwordProfileId,
        purpose: "reset_password",
      });

      setStatus({
        type: "success",
        message: "Check your email for instructions to reset your password.",
      });
    } catch (error) {
      console.error("Password reset request failed:", error);
      setStatus({
        type: "error",
        message: "Failed to request password reset. Please try again.",
      });
    } finally {
      setLoading(false);
    }
  };

  return (
    
      Reset Your Password
      {status.message && (
        {status.message}
      )}
      <form onSubmit={handleSubmit}>
        
          <label htmlFor="username">Email Address</label>
          <input
            type="email"
            id="username"
            value={username}
            onChange={(e) => setUsername(e.target.value)}
            required
            disabled={loading}
          />
        
        <button type="submit" disabled={loading} className="reset-button">
          {loading ? "Sending..." : "Reset Password"}
        </button>
      </form>
    
  );
}

export default RequestPasswordReset;
```

:::info
For a complete implementation of the password reset request form, check out the [ForgotPasswordForm component](https://github.com/elasticpath/composable-frontend/tree/main/examples/shopper-accounts-authentication/src/components/forgot-password) in the Shopper Accounts Authentication example.
:::

## 4 · Confirming the password reset

Create a page component to handle the one-time password token and allow the user to set a new password:

```tsx
// pages/reset-password.js (Next.js example)
import React, { useState, useEffect } from "react";
import { useRouter } from "next/router";
import {
  createAnAccessToken,
  updateUserAuthenticationPassword,
} from "@epcc-sdk/sdks-shopper";
import { useAuth } from "../context/auth-context"; // Assumed auth context for managing tokens

function ResetPassword() {
  const [password, setPassword] = useState("");
  const [confirmPassword, setConfirmPassword] = useState("");
  const [otp, setOtp] = useState("");
  const [username, setUsername] = useState("");
  const [passwordProfileId, setPasswordProfileId] = useState("");
  const [status, setStatus] = useState({ type: "", message: "" });
  const [loading, setLoading] = useState(false);
  const router = useRouter();

  useEffect(() => {
    // Extract parameters from URL
    if (router.isReady) {
      const { token, username: user, profile_id } = router.query;
      if (token) setOtp(token);
      if (user) setUsername(user);
      if (profile_id) setPasswordProfileId(profile_id);
    }
  }, [router.isReady, router.query]);

  const handleSubmit = async (e) => {
    e.preventDefault();

    // Basic validation
    if (password !== confirmPassword) {
      setStatus({
        type: "error",
        message: "Passwords do not match",
      });
      return;
    }

    if (password.length < 8) {
      setStatus({
        type: "error",
        message: "Password must be at least 8 characters long",
      });
      return;
    }

    setLoading(true);
    setStatus({ type: "", message: "" });

    try {
      // Get an Account Management Authentication Token using one-time password
      const accountTokenResponse = await createAnAccessToken({
        grant_type: "account_management_authentication_token",
        client_id: process.env.NEXT_PUBLIC_CLIENT_ID,
        token_type: "one_time_password_token",
        one_time_password_token: otp,
        username: username,
        password_profile_id: passwordProfileId,
      });

      const accountToken =
        accountTokenResponse.account_management_authentication_token;

      // Update user's password
      await updateUserAuthenticationPassword({
        password,
        password_profile_id: passwordProfileId,
        username,
        account_token: accountToken,
      });

      setStatus({
        type: "success",
        message: "Password has been reset successfully!",
      });

      // Redirect to login after a short delay
      setTimeout(() => {
        router.push("/login");
      }, 3000);
    } catch (error) {
      console.error("Password reset confirmation failed:", error);
      setStatus({
        type: "error",
        message:
          "Failed to reset password. The token may be invalid or expired.",
      });
    } finally {
      setLoading(false);
    }
  };

  return (
    
      Set New Password
      {status.message && (
        {status.message}
      )}
      {otp && username && passwordProfileId ? (
        <form onSubmit={handleSubmit}>
          
            <label htmlFor="password">New Password</label>
            <input
              type="password"
              id="password"
              value={password}
              onChange={(e) => setPassword(e.target.value)}
              required
              disabled={loading}
              minLength={8}
            />
          
          
            <label htmlFor="confirmPassword">Confirm Password</label>
            <input
              type="password"
              id="confirmPassword"
              value={confirmPassword}
              onChange={(e) => setConfirmPassword(e.target.value)}
              required
              disabled={loading}
              minLength={8}
            />
          
          <button type="submit" disabled={loading} className="reset-button">
            {loading ? "Resetting..." : "Reset Password"}
          </button>
        </form>
      ) : (
        
          Missing required parameters. Please check your reset link.
        
      )}
    
  );
}

export default ResetPassword;
```

:::info
For a complete implementation of the password reset confirmation page, check out the [ResetPasswordForm component](https://github.com/elasticpath/composable-frontend/tree/main/examples/shopper-accounts-authentication/src/components/reset-password) in the Shopper Accounts Authentication example.
:::

## 5 · Configuring the email webhook

When a user requests a password reset, an event is triggered that your webhook should handle. Your webhook implementation should:

1. Extract the one-time password token and user information from the event
2. Send an email to the user with a link to your reset password page
3. Include the token, username, and password profile ID as parameters

Example link format:

```
https://your-domain.com/reset-password?token=abc123&username=user@example.com&profile_id=password_profile_123
```

## 6 · SDK functions reference

The Shopper SDK provides the following functions for password reset:

### createOneTimePasswordTokenRequest

```ts
import { createOneTimePasswordTokenRequest } from "@epcc-sdk/sdks-shopper";

/**
 * Request a one-time password token for reset
 */
async function requestReset(username, passwordProfileId) {
  return createOneTimePasswordTokenRequest({
    username,
    password_profile_id: passwordProfileId,
    purpose: "reset_password",
  });
}
```

### createAnAccessToken (for Account Management Authentication)

```ts
import { createAnAccessToken } from "@epcc-sdk/sdks-shopper";

/**
 * Exchange a one-time password token for an Account Management Authentication Token
 */
async function getAccountManagementToken(username, passwordProfileId, token) {
  return createAnAccessToken({
    grant_type: "account_management_authentication_token",
    client_id: process.env.CLIENT_ID,
    token_type: "one_time_password_token",
    one_time_password_token: token,
    username: username,
    password_profile_id: passwordProfileId,
  });
}
```

### updateUserAuthenticationPassword

```ts
import { updateUserAuthenticationPassword } from "@epcc-sdk/sdks-shopper";

/**
 * Update a user's password
 */
async function updatePassword(
  username,
  passwordProfileId,
  newPassword,
  accountToken,
) {
  return updateUserAuthenticationPassword({
    password: newPassword,
    password_profile_id: passwordProfileId,
    username,
  });
}
```

## 7 · Real-world implementation example

For a complete implementation of password reset functionality in a Next.js application, refer to the [Shopper Accounts Authentication example](https://github.com/elasticpath/composable-frontend/tree/main/examples/shopper-accounts-authentication) in the Composable Frontend repository. This example includes:

- Proper authentication state management
- Form validation
- Error handling
- Integration with the Elastic Path Shopper SDK
- Complete password reset flow

Key components to review:

1. [ForgotPasswordForm](https://github.com/elasticpath/composable-frontend/tree/main/examples/shopper-accounts-authentication/src/components/forgot-password) - Initiates the password reset process
2. [ResetPasswordForm](https://github.com/elasticpath/composable-frontend/tree/main/examples/shopper-accounts-authentication/src/components/reset-password) - Allows users to set a new password
3. Authentication utility functions that handle token management

## 8 · Security considerations

- **Token expiration**: One-time password tokens expire after 10 minutes
- **Rate limiting**: Implement rate limiting for password reset requests to prevent abuse
- **Secure emails**: Ensure password reset emails don't contain the actual password
- **Notification**: Consider notifying users via alternative channels when password changes occur
- **Password strength**: Enforce strong password policies during the reset process
- **HTTPS**: Always use HTTPS for your reset password pages

## 9 · Error handling

Common errors to handle include:

- Invalid or expired tokens
- User not found
- Password doesn't meet requirements
- Network failures

```ts
try {
  // Get account management token using one-time password token
  const tokenResponse = await createAnAccessToken({
    grant_type: "account_management_authentication_token",
    client_id: process.env.CLIENT_ID,
    token_type: "one_time_password_token",
    one_time_password_token: token,
    username: username,
    password_profile_id: passwordProfileId,
  });

  // Success handling
} catch (error) {
  if (error.status === 404) {
    // User not found or token invalid
    showError(
      "Invalid or expired reset link. Please request a new password reset.",
    );
  } else if (error.status === 422) {
    // Validation error
    showError("Invalid information provided. Please try again.");
  } else if (error.status === 401) {
    // Invalid token
    showError("Invalid or expired token. Please request a new password reset.");
  } else {
    // Generic error
    showError("An error occurred. Please try again later.");
  }
}
```

For complete implementations, check out the [authentication examples](https://github.com/elasticpath/composable-frontend/tree/main/examples) in the Composable Frontend repository, specifically the [Shopper Accounts Authentication example](https://github.com/elasticpath/composable-frontend/tree/main/examples/shopper-accounts-authentication).

---

## Token Refresh

## Why token refresh matters 🔄

Both implicit tokens and Account Management tokens have limited lifespans. The new Elastic Path SDK (`@epcc-sdk/sdks-shopper`) handles token refresh automatically, but understanding the process helps you customize behavior for your specific needs.

:::info
With `configureClient` or `createShopperClient`, token refresh is handled automatically by default. This guide shows how to customize that behavior or implement manual refresh when needed.
:::

---

## 1 · Understanding token expiration

**Implicit tokens** expire after approximately 1 hour (3600 seconds).

**Account Management tokens** have configurable expiration times:

- Default expiration can be set by store administrators using `account_management_authentication_token_timeout_secs`
- Useful for implementing idle timeout security features

**The SDK handles this automatically** by default. You can customize this behavior through custom storage adapters.

## 2 · Automatic token refresh (recommended)

The new SDK handles token refresh automatically when you use `configureClient` or `createShopperClient`:

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

// The SDK automatically:
// - Fetches tokens on first API call
// - Refreshes before expiry
// - Retries on 401 errors
export const client = configureClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage"
  }
);
```

No manual refresh code needed! The SDK handles everything internally.

### Customizing refresh behavior

To customize token refresh behavior, you would implement a custom storage adapter that controls when and how tokens are refreshed. The SDK's automatic refresh behavior is built-in and not directly configurable through options.

## 3 · Manual token refresh

If you need direct control over token refresh (e.g., for custom authentication flows):

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { client, auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID
    // Note: To disable automatic token management, 
    // you would need to implement custom storage that 
    // controls when tokens are fetched/refreshed
  }
);

// Manually get and refresh tokens
async function manualTokenManagement() {
  // Get valid token (auto-refreshes if needed)
  const token = await auth.getValidAccessToken();
  console.log("Token obtained:", token);
  
  // Get current token without refresh
  const snapshot = await auth.getSnapshot();
  console.log("Current token:", snapshot?.access_token);
  
  // Force manual refresh
  const newToken = await auth.refresh();
  console.log("Token refreshed:", newToken);
}
```

### Implementing custom refresh logic

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { client, auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: {
      get: async (key) => {
        // Custom storage retrieval
        const stored = localStorage.getItem(key);
        if (stored) {
          const data = JSON.parse(stored);
          // Check custom expiry logic
          if (data.expiresAt && Date.now() > data.expiresAt - 300000) {
            // Refresh 5 minutes before expiry
            return null; // Force refresh
          }
          return data.token;
        }
        return null;
      },
      set: async (key, value) => {
        // Store with custom expiry tracking
        localStorage.setItem(key, JSON.stringify({
          token: value,
          expiresAt: Date.now() + 3600000, // 1 hour
          refreshedAt: Date.now()
        }));
      },
      remove: async (key) => {
        localStorage.removeItem(key);
      }
    }
  }
);
```

## 4 · Refreshing Account Management tokens

Account Management tokens can be refreshed using the refresh token that's provided during initial authentication:

```ts
import { createAnAccessToken, client } from "@epcc-sdk/sdks-shopper";

// Setup Account token refresh
function setupAccountTokenRefresh() {
  let refreshTimeout;

  async function refreshAccountToken() {
    const refreshToken = localStorage.getItem("ep_account_refresh_token");

    if (!refreshToken) {
      console.error("No refresh token available");
      return null;
    }

    try {
      const { access_token, refresh_token, expires_in } =
        await createAnAccessToken({
          grant_type: "refresh_token",
          client_id: process.env.CLIENT_ID,
          refresh_token: refreshToken,
        });

      // Store the new tokens
      localStorage.setItem("ep_account_token", access_token);
      localStorage.setItem("ep_account_refresh_token", refresh_token);

      // Calculate expiration time
      const expiryTime = Date.now() + expires_in * 1000;
      localStorage.setItem("ep_account_token_expiry", expiryTime.toString());

      // Schedule next refresh at 80% of token lifetime
      const refreshTime = expires_in * 0.8 * 1000;
      refreshTimeout = setTimeout(refreshAccountToken, refreshTime);

      return access_token;
    } catch (error) {
      console.error("Account token refresh failed:", error);
      // Clear tokens on refresh failure - user needs to re-login
      localStorage.removeItem("ep_account_token");
      localStorage.removeItem("ep_account_refresh_token");
      localStorage.removeItem("ep_account_token_expiry");
      return null;
    }
  }

  // Clear previous timeouts on re-setup
  if (refreshTimeout) clearTimeout(refreshTimeout);

  // Initial check - if we have a refresh token, try to refresh
  const hasRefreshToken = !!localStorage.getItem("ep_account_refresh_token");
  if (hasRefreshToken) {
    return refreshAccountToken();
  }

  return Promise.resolve(null);
}

// Initialize on app start
setupAccountTokenRefresh().then((token) => {
  if (token) {
    console.log("Account token refreshed");
  }
});
```

## 5 · Handling both token types together

When using both implicit and Account Management tokens, the SDK can manage both:

For a complete solution, combine both token refresh mechanisms:

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

// Configure client with custom auth handling for both tokens
export const client = configureClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage",
    // The SDK automatically manages the implicit token
    // You handle the Account Management token separately
    interceptors: {
      request: async (config) => {
        // The SDK already added the implicit token
        // Add Account Management token if available
        const accountToken = localStorage.getItem("ep_account_token");
        if (accountToken) {
          config.headers["EP-Account-Management-Authentication-Token"] = accountToken;
        }
        return config;
      }
    }
  }
);

// Separate function to refresh Account Management token
async function refreshAccountToken() {
  const refreshToken = localStorage.getItem("ep_account_refresh_token");
  if (!refreshToken) return;
  
  try {
    // Call your Account Management token refresh endpoint
    const response = await fetch("/api/auth/refresh", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ refresh_token: refreshToken })
    });
    
    const { access_token, refresh_token: newRefreshToken } = await response.json();
    localStorage.setItem("ep_account_token", access_token);
    localStorage.setItem("ep_account_refresh_token", newRefreshToken);
  } catch (error) {
    console.error("Account token refresh failed:", error);
    // Clear tokens and redirect to login
    localStorage.removeItem("ep_account_token");
    localStorage.removeItem("ep_account_refresh_token");
  }
}
```

## 6 · Monitoring token state

To monitor token state and handle authentication events in your application:

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { client, auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage"
  }
);

// Check authentication state
async function checkAuthState() {
  // Get current token snapshot
  const snapshot = await auth.getSnapshot();
  const isAuthenticated = !!snapshot?.access_token;
  console.log("Authenticated:", isAuthenticated);
  
  if (!isAuthenticated) {
    // Handle unauthenticated state
    window.location.href = "/login";
  }
}

// Periodically check auth state if needed
setInterval(checkAuthState, 60000); // Check every minute
```
## 7 · Advanced scenarios

### Force token refresh

For critical operations, force a fresh token:

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { client, auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);

// Ensure fresh token before checkout
async function startCheckout() {
  // Force a token refresh
  await auth.refresh();
  
  // Proceed with checkout
  return initiateCheckout();
}
```

### Handling multiple tabs

When using `localStorage` as the storage option, tokens are naturally shared across tabs since localStorage is synchronized across all tabs of the same origin:

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

// Using localStorage enables natural cross-tab token sharing
export const client = configureClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage"
  }
);
```

If you need to react to token changes from other tabs, you can use the browser's native storage event:

```ts
// Listen for token changes from other tabs
window.addEventListener('storage', (event) => {
  if (event.key === '_store_ep_credentials' || event.key?.startsWith('ep_')) {
    console.log('Token updated in another tab');
    // Your custom handling here
  }
});
```

### Handling network interruptions

The SDK includes built-in retry logic for failed requests. To implement custom retry behavior, you can wrap API calls with your own retry logic:

```ts
async function callWithRetry(apiCall, maxRetries = 3, delay = 1000) {
  let lastError;
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await apiCall();
    } catch (error) {
      lastError = error;
      console.log(`Attempt ${i + 1} failed:`, error.message);
      
      if (i < maxRetries - 1) {
        // Wait before retrying
        await new Promise(resolve => setTimeout(resolve, delay * (i + 1)));
      }
    }
  }
  
  throw lastError;
}

// Usage
const products = await callWithRetry(() => getByContextAllProducts());
```

### Server-side token refresh (Next.js example)

For SSR applications, handle token refresh on the server:

```ts
// app/api/auth/refresh/route.ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";
import { cookies } from "next/headers";

export async function POST() {
  const cookieStore = cookies();
  const currentToken = cookieStore.get("ep_token");
  
  const { client, auth } = createShopperClient(
    { baseUrl: process.env.EPCC_BASE_URL },
    {
      clientId: process.env.EPCC_CLIENT_ID,
      storage: {
        get: async () => currentToken?.value,
        set: async (key, value) => {
          cookieStore.set("ep_token", value, {
            httpOnly: true,
            secure: true,
            sameSite: "lax",
            maxAge: 3600 // 1 hour
          });
        },
        remove: async () => {
          cookieStore.delete("ep_token");
        }
      }
    }
  );
  
  try {
    const newToken = await auth.refresh();
    return Response.json({ success: true });
  } catch (error) {
    return Response.json({ error: "Refresh failed" }, { status: 401 });
  }
}
```

## Summary

The new Elastic Path SDK (`@epcc-sdk/sdks-shopper`) dramatically simplifies token refresh:

1. **Automatic by default** - The SDK handles token refresh automatically with `configureClient`
2. **Customizable behavior** - Override refresh timing, retry logic, and storage
3. **Event-driven** - React to token events for custom workflows
4. **Cross-tab sync** - Automatic synchronization when using localStorage
5. **SSR-friendly** - Works with server-side rendering and custom storage adapters

For most use cases, simply using `configureClient` with default settings provides a complete token refresh solution. Only implement custom refresh logic when you have specific requirements beyond the SDK's automatic handling.

For complete implementations, check out the [authentication examples](https://github.com/elasticpath/composable-frontend/tree/main/examples) in the Composable Frontend repository.

---

## Token Management

## Why token management matters 🔐

Every storefront request to Elastic Path **must carry a valid OAuth 2.0 access‑token** in the `Authorization` header.  
Because the shopper experience runs in the browser, the recommended flow is the **implicit token grant**: no `client_secret` travels to the client, yet the token still authorizes catalog, cart, and checkout calls.  

With the new SDK (`@epcc-sdk/sdks-shopper`), token management is largely automated through `configureClient` or `createShopperClient`, but understanding the underlying process helps you customize behavior when needed.

:::tip
For complete working implementations, check our [Composable Frontend examples repository](https://github.com/elasticpath/composable-frontend/tree/main/examples) which includes ready-to-use patterns for:

- [Authentication with local storage](https://github.com/elasticpath/composable-frontend/tree/main/examples/authentication-local-storage)
- [Authentication with server cookies](https://github.com/elasticpath/composable-frontend/tree/main/examples/authentication-server-cookie)
  :::

---

## 1 · Automatic token management (recommended)

The SDK handles token generation automatically:

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

// Configure once - tokens are managed automatically
export const client = configureClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage" // or "cookie" or custom
  }
);

// Make API calls - authentication happens automatically
import { getByContextAllProducts } from "@epcc-sdk/sdks-shopper";

const products = await getByContextAllProducts();
```

### Manual token generation (when needed)

If you need direct control:

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { client, auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);

// Manually get token
const token = await auth.getValidAccessToken();
console.log("Token:", token);
```

## 2 · Storage options with the SDK

The SDK supports multiple storage patterns out of the box:

### localStorage (default for SPAs)

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

export const client = configureClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage" // Persists across tabs and refreshes
  }
);
```

### Cookie storage (better for SSR)

```ts
export const client = configureClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: "cookie",
    cookieOptions: {
      domain: ".yourdomain.com",
      secure: true,
      sameSite: "lax",
      httpOnly: false // Set true if handling through server proxy
    }
  }
);
```

### Custom storage adapter

```ts
export const client = configureClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  {
    clientId: process.env.CLIENT_ID,
    storage: {
      get: async (key) => {
        // Your custom retrieval logic
        return await customStore.get(key);
      },
      set: async (key, value) => {
        await customStore.set(key, value);
      },
      remove: async (key) => {
        await customStore.delete(key);
      }
    }
  }
);
```

:::info
**Complete examples on GitHub**

- [Local Storage Authentication Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/authentication-local-storage) - Implementation of client-side token storage
- [Server Cookie Authentication Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/authentication-server-cookie) - Implementation of server-side HttpOnly cookie pattern
  :::

:::warning
Security note: localStorage is vulnerable to XSS exfiltration; if you control a server layer, prefer an HttpOnly cookie
:::

## 3 · How the SDK attaches tokens

With `configureClient` or `createShopperClient`, tokens are automatically attached to all requests:

```ts
import { configureClient, getByContextAllProducts } from "@epcc-sdk/sdks-shopper";

// Configure once
const client = configureClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);

// Token is automatically added to Authorization header
const products = await getByContextAllProducts();
// Header sent: Authorization: Bearer <token>
```

### Adding custom headers with interceptors

After configuring the client, you can add interceptors:

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

export const client = configureClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);

// Add interceptors after configuration
client.interceptors.request.use((request, options) => {
  // SDK already added the implicit token
  // Add any additional headers
  request.headers.set("X-Custom-Header", "value");
  return request;
});
```

### Managing both Implicit and Account tokens

As described in the [Authentication Concepts](../overview) guide, many storefront experiences require both an implicit token and an Account Management Authentication token. With the new SDK:

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

export const client = configureClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);

// Add account token via interceptor
client.interceptors.request.use((request, options) => {
  // The SDK already handles the implicit token
  // Add account token for personalized shopper access
  const accountToken = localStorage.getItem("ep_account_token");
  if (accountToken) {
    request.headers.set("EP-Account-Management-Authentication-Token", accountToken);
  }
  return request;
});
```

This pattern ensures that:

1. The implicit token is automatically managed by the SDK
2. The Account Management Authentication token is added when available
3. Both tokens are sent with appropriate headers

### Server‑side with Next.js

```ts
// app/api/products/route.ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";
import { cookies } from "next/headers";

export async function GET() {
  const cookieStore = cookies();
  const token = cookieStore.get("ep_implicit_token");

  const { client } = createShopperClient(
    { baseUrl: "https://euwest.api.elasticpath.com" },
    {
      clientId: process.env.EPCC_CLIENT_ID,
      storage: {
        get: async () => token?.value,
        set: async () => {}, // Handled by server
        remove: async () => {}
      }
    }
  );

  const { getByContextAllProducts } = await import("@epcc-sdk/sdks-shopper");
  const products = await getByContextAllProducts();
  
  return Response.json(products);
}
```

## 4 · Token expiration and refresh

The SDK automatically handles token expiration and refresh:

- **Implicit tokens** expire in approximately 1 hour (3600 seconds)
- **Account Management tokens** have configurable expiration times
- **Automatic refresh** happens before expiry (default: 60 seconds before expiration)

### How automatic refresh works

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

// The SDK automatically:
// 1. Tracks token expiry time
// 2. Refreshes 60 seconds before expiration
// 3. Retries on 401 errors
// 4. Updates stored tokens (key: _store_ep_credentials)
export const client = configureClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);
```

### Checking token state

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { client, auth } = createShopperClient(
  { baseUrl: "https://euwest.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);

// Get current token (triggers fetch/refresh if needed)
const token = await auth.getValidAccessToken();

// Get current token without triggering refresh
const snapshot = await auth.getSnapshot();

// Force token refresh
const newToken = await auth.refresh();

// Clear authentication if needed
await auth.clear();
```

:::info
For advanced token refresh strategies and manual control, see the [Token Refresh guide](./refresh-token).
:::

## Summary

The new Elastic Path SDK (`@epcc-sdk/sdks-shopper`) dramatically simplifies token management:

1. **Automatic token handling** - `configureClient` manages the complete token lifecycle
2. **Flexible storage** - Built-in support for localStorage, cookies, or custom adapters
3. **Seamless authentication** - Tokens are automatically added to all API requests
4. **Account token support** - Easy integration of both implicit and account tokens

For most use cases, simply using `configureClient` provides complete token management. Only implement custom logic when you have specific requirements beyond the SDK's automatic handling.

By combining the SDK's automatic token management with the patterns from the [Token Refresh guide](./refresh-token), you'll create a robust authentication system with minimal code.

[1]: https://community.auth0.com/t/why-is-storing-tokens-in-memory-recommended/17742 "Why is storing tokens in-memory recommended? - Auth0 Community"
[2]: https://auth0.com/blog/secure-browser-storage-the-facts/ "Secure Browser Storage: The Facts - Auth0"
[3]: https://auth0.com/docs/security/data-security/token-storage#browser-in-memory-scenarios "Token Storage - Auth0"
[4]: https://auth0.com/docs/security/data-security/token-storage#regular-web-apps-traditional "Regular Web Apps - Auth0"

---

## Overview(Authentication)

## Why read this overview?

Before you copy a single SDK snippet, you need to know **which token your storefront should use, how that token is issued, and the security trade-offs of storing it in a browser or on the server**. Elastic Path Commerce Cloud exposes several tokens types; for shopper storefronts you'll almost always rely on the **implicit token + Account-Auth token** pair. This page clarifies the moving parts so the task-oriented guides make sense.

---

## 1 · Token types at a glance

| Token                              | Who uses it                                        | Typical scope                                         | How it's issued                                   |
| ---------------------------------- | -------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------- |
| **Implicit shopper token**         | Any storefront: SPA, PWA, SSR, SSG                 | Read/write carts, orders, catalog for _one_ shopper   | `grant_type=implicit` – no client_secret required |
| **Account Management Auth token**  | B2C and B2B flows – identifies individual shoppers | Impersonate account member; access personal resources | `POST /v2/account-members/tokens`                 |
| **Client-credentials (app) token** | Server-side jobs, SSR, integrations                | Store-wide admin scope                                | `grant_type=client_credentials` with secret       |

> The legacy **Customer token** exists for older builds; new storefronts should create **Accounts** + members instead.

:::info
All API endpoints require authentication. The implicit token is attached to every request using the `Authorization: Bearer <token>` header:

```
Authorization: Bearer 212LJ3k0i2382364HIUEjfeJB98yvH
```

Access tokens expire after 1 hour, requiring regeneration. The Shopper SDK can automatically handle this for you with appropriate setup.
:::

---

## 2 · Client Credentials vs. Implicit

According to the [Elastic Path documentation](https://elasticpath.dev/docs/api/authentication/authentication):

- **`implicit`**: Generates a token with limited, mostly read-only access. Designed for client-side browser applications (frontends).
- **`client_credentials`**: Provides full read and write access. Used for all administrative tasks (CRUD operations) at the backend.

The distinction is important for security - never expose `client_credentials` tokens in browser code.

---

## 3 · Shopper Authentication

### Account-based Authentication (Recommended)

For shopper experiences, you typically use two tokens together:

1. An **implicit access token** (basic API access)
2. An **Account Management authentication token** (shopper-specific resources)

Account Management authentication isn't just for B2B scenarios - it's the standard approach for any personalized shopping experience in both B2C and B2B contexts. When a customer logs into a storefront, the Account Management token identifies them and grants access to their specific data.

When using Account Management APIs, the account authentication token is set in the `EP-Account-Management-Authentication-Token` header, granting access to resources associated with the account: carts, orders, catalogs, and addresses.

### Customer Authentication (Legacy)

:::caution
Customer tokens are a legacy authentication mechanism. For new implementations, use Account-based authentication instead.
:::

The legacy customer token is set in the `X-Moltin-Customer-Token` header to access customer-specific resources.

---

## 4 · Typical shopper auth flow

```mermaid
sequenceDiagram
  participant App as Storefront SPA
  participant EP as Elastic Path API

  App->>EP: POST /account (create)
  EP-->>App: Account created (one-time setup)
  App->>EP: POST /account-members (Jane)
  EP-->>App: Member created (one-time setup)

  Note over App,EP: Authentication process (for each session)

  App->>EP: POST /oauth/token (grant_type=implicit)
  EP-->>App: { access_token, expires_in }
  Note right of App: Implicit token• Valid for ~1 hour• Required for all API calls• Bearer token in Authorization header

  App->>EP: GET /v2/account-members/tokens (get account auth token)
  EP-->>App: { token }
  Note right of App: Account token• Long-lived (tied to user session)• Identifies the specific shopper• Set in EP-Account-Management-Authentication-Token header

  App->>EP: GET /v2/carts (with both tokens in headers)
  EP-->>App: User's carts (personalized response)
```

### Token lifecycle differences

**Implicit token**:

- **Purpose**: Provides basic API access to Elastic Path endpoints
- **Lifespan**: Short-lived (~1 hour)
- **Renewal**: Must be refreshed regularly using `createAnAccessToken` when expired
- **Header**: `Authorization: Bearer <token>`
- **Scope**: Limited access, mostly read permissions with some write capabilities for the current session

**Account Management token**:

- **Purpose**: Associates requests with a specific shopper's account
- **Lifespan**: Configurable per store (can be set to implement idle timeout)
- **Renewal**: Can be refreshed using the refresh token provided with the initial authentication
- **Header**: `EP-Account-Management-Authentication-Token: <token>`
- **Scope**: Grants access to the shopper's personal resources (carts, orders, addresses)

:::info
**Configurable Expiration & Idle Timeout**

The Account Management Authentication Token's expiration time can be configured on a per-store basis:

1. Store administrators can set `account_management_authentication_token_timeout_secs` to implement idle timeout
2. This allows for automatic logout after periods of inactivity
3. While users are active, their tokens should be refreshed periodically to maintain their session

The timeout setting is particularly useful for implementing security features like session timeout in B2B applications or high-security storefronts.
:::

### Working together

Every API request requires the implicit token for base authentication. For personalized operations (viewing a user's cart, placing an order), you also need to include the Account Management token in a separate header. Think of the implicit token as your "API pass" and the Account Management token as your "personalization identifier."

### Token Refresh Strategy

For a complete authentication system, implement these refresh strategies:

**Implicit token refresh**:

- Refresh before expiration (proactive) or on 401 errors (reactive)
- Requires a new call to `createAnAccessToken` with grant_type=implicit

**Account Management token refresh**:

- Use the refresh token provided during initial authentication
- For self-signup flows, the initial token request with credentials provides both the token and refresh token
- Implement idle timeout by stopping refreshes after a period of inactivity
- See [Authentication using Self Sign Up](https://elasticpath.dev/guides/How-To/Accounts/authenticate-using-self-signup) for complete implementation details

---

## 5 · Where to store the token?

### Managing both tokens

You need to store and manage both the **implicit token** and the **Account Management token**:

1. **Implicit token** - required for all API requests in the `Authorization` header
2. **Account Management token** - required for personalized shopping in the `EP-Account-Management-Authentication-Token` header

Both tokens should be stored using the same security approach. The storage options below apply to both tokens.

| Storage                                      | Pros                                   | Cons                                                                                |
| -------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------- |
| `localStorage`                               | Persist across tabs; simplest          | Readable by any XSS script ([Auth0][2])                                             |
| **Readable cookie** (`Secure; SameSite=Lax`) | Auto-sent to same-site requests        | Vulnerable to CSRF (mitigate with anti-CSRF tokens) ([OWASP Cheat Sheet Series][3]) |
| **HttpOnly cookie** (server proxy)           | Immune to XSS; ideal for SSR           | JS can't read it; every request must hit server ([Auth0 Community][4])              |
| In-memory JS variable                        | Least surface area; cleared on refresh | User loses session on reload                                                        |

**Best practice:** For a pure SPA, combine **in-memory** storage plus a silent token refresh (see the refresh how-to); if you already proxy API calls through your Next.js server, prefer an **HttpOnly** cookie.

:::tip
When storing both tokens, consider using a consistent naming pattern such as `ep_implicit_token` and `ep_account_token` to clearly identify each token's purpose.
:::

---

## 6 · Token lifetime & refresh

- Implicit tokens default to **≈ 3600 s (1 h)** ([Elastic Path Documentation][5]).
- When the SDK gets `401 Unauthorized`, refresh with a _new_ implicit grant and retry once.
- For long-running B2B dashboards, schedule a refresh 5 minutes before `expires_in`.

> Refresh tokens are **not** issued for implicit grants, so plan on silent re-auth or redirect re-login ([Auth0][6]).

---

## 7 · Security checklist 🛡️

- Use HTTPS **everywhere**; the API rejects non-TLS.
- Set `Secure` and `SameSite=Lax` on any cookie that carries a token.
- Protect against XSS: Content-Security-Policy, strict lint on unescaped HTML.
- Never include client_secret in client-side code; use implicit flow for frontends.

---

## 8 · What's next?

- **[Quick-start tutorial](./quickstart)** – hands-on code for account + member + login.
- **[Token-management how-to](./how-to/token-management)** – concrete storage snippets.
- **OAuth Social Login** – exchange Google ID-tokens via `socialLogin()`.

Read these in order or jump straight to the task you need—this concepts page will be here whenever you need a refresher.

[1]: https://elasticpath.dev/docs/api/carts/get-carts "Get Shopper Carts | Elastic Path Documentation"
[2]: https://auth0.com/blog/secure-browser-storage-the-facts/ "Secure Browser Storage: The Facts - Auth0"
[3]: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html "Cross-Site Request Forgery Prevention - OWASP Cheat Sheet Series"
[4]: https://community.auth0.com/t/why-is-storing-tokens-in-memory-recommended/17742 "Why is storing tokens in-memory recommended? - Auth0 Community"
[5]: https://elasticpath.dev/docs/api/authentication/authentication "Authentication | Elastic Path Documentation"
[6]: https://auth0.com/docs/get-started/authentication-and-authorization-flow "Authentication and Authorization Flows - Auth0"

---

## Quick Start

## Why you need this guide ⚡

Every storefront request to Elastic Path Commerce Cloud **must carry an access-token** in the `Authorization` header. For browser code you nearly always use an **implicit shopper token** – a scoped, read-mostly token that keeps your `client_secret` out of the client bundle.
This guide shows the shortest path: configure the TypeScript **Shopper SDK** and let it handle authentication for you.

:::note
Account tokens are also available for authenticated user scenarios, but are not covered in this quickstart. See the [Token Management guide](./how-to/token-management) for detailed information about account tokens and other authentication methods.
:::

---

## Prerequisites

| What                  | Value                                |
| --------------------- | ------------------------------------ |
| API base URL          | `https://useast.api.elasticpath.com` |
| Application client-ID | `<YOUR_CLIENT_ID>`                   |
| Package               | `npm i @epcc-sdk/sdks-shopper`       |

---

## 1 · Configure the SDK with built-in authentication

The new SDK handles authentication automatically. Choose one of these approaches:

### Option A: Global client configuration (Recommended)

```ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

// Configure once in your app initialization
export const client = configureClient(
  { 
    baseUrl: "https://useast.api.elasticpath.com" 
  },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage" // or "cookie" or custom adapter
  }
);
```

### Option B: Standalone client instance

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

// Create a client instance
const { client, auth } = createShopperClient(
  { 
    baseUrl: "https://useast.api.elasticpath.com" 
  },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage"
  }
);

// Export for use in your app
export { client };
```

:::info
The SDK automatically:
- Fetches an implicit token on first API call
- Stores the token in your chosen storage (default key: `_store_ep_credentials`)
- Refreshes tokens 60 seconds before expiry
- Adds the Authorization header to all requests
:::

## 2 · Use the SDK - authentication happens automatically

```ts
import { getByContextAllProducts } from "@epcc-sdk/sdks-shopper";

// No need to manually handle tokens!
const response = await getByContextAllProducts({
  query: {
    "page[limit]": 10
  }
});

console.log(`Found ${response.data?.data?.length} products`);
```

## 3 · Storage options

The SDK supports different storage mechanisms:

```ts
// localStorage (default for SPAs)
configureClient(apiConfig, {
  clientId: process.env.CLIENT_ID,
  storage: "localStorage"
});

// Cookies (better for SSR)
configureClient(apiConfig, {
  clientId: process.env.CLIENT_ID,
  storage: "cookie",
  cookieOptions: {
    domain: ".yourdomain.com",
    secure: true,
    sameSite: "lax"
  }
});

// Custom storage adapter
configureClient(apiConfig, {
  clientId: process.env.CLIENT_ID,
  storage: {
    get: async (key) => {
      // Your custom storage logic
      return await customStore.get(key);
    },
    set: async (key, value) => {
      await customStore.set(key, value);
    },
    remove: async (key) => {
      await customStore.delete(key);
    }
  }
});
```

## 4 · Manual token handling (if needed)

If you need direct control over authentication:

```ts
import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { client, auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);

// Get token manually
const token = await auth.getValidAccessToken();
console.log("Token:", token);

// Get current token without triggering refresh
const snapshot = await auth.getSnapshot();
console.log("Current token:", snapshot?.access_token);

// Force token refresh
const newToken = await auth.refresh();
console.log("Refreshed token:", newToken);

// Clear authentication
await auth.clear();
```

:::tip
For complete working implementations, check our [Composable Frontend examples repository](https://github.com/elasticpath/composable-frontend/tree/main/examples) which includes ready-to-use patterns for:

- [Authentication with local storage](https://github.com/elasticpath/composable-frontend/tree/main/examples/authentication-local-storage)
- [Authentication with server cookies](https://github.com/elasticpath/composable-frontend/tree/main/examples/authentication-server-cookie)
:::

## Next steps

- For complex authentication scenarios including account tokens, see the [Token Management guide](./how-to/token-management)
- For logout and session management, see the [Logout guide](./how-to/logout)
- For password reset functionality, see the [Password Reset guide](./how-to/password-reset)

---

## Add Items to Cart(How-to)


This guide explains how to add various types of items to an existing shopping cart in your Elastic Path implementation.

## Adding Standard Products

The `manageCarts` method allows you to add regular products to a customer's cart:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

// Get the current cart ID
const cartId = getCartId();

// Add a product to cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "cart_item",
      id: "product-12345",
      quantity: 1,
    },
  },
});
```

### Location-Based Inventory
You can specify a `location` to target inventory from a specific warehouse or store. This is useful for multi-location setups. Use the `slug` of the location:

```javascript
// Add a product with location-based inventory
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      ...,
      location: "boston" // Optional location for inventory
    },
  },
});
```

## Adding Custom Items

Custom items are useful for items that aren't managed in your product catalog:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

// Get the current cart ID
const cartId = getCartId();

// Add a custom item directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "custom_item",
      name: "Premium Service Fee",
      sku: "service-fee-premium",
      quantity: 1,
      price: {
        amount: 1995, // $19.95 in minor units
        includes_tax: false,
      },
      description: "Premium service package fee",
    },
  },
});
```

### Example: Adding a Gift Card

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

const cartId = getCartId();

// Add a gift card directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "custom_item",
      name: "Gift Card - $50",
      sku: "giftcard-50",
      quantity: 1,
      price: {
        amount: 5000, // $50 in minor units (cents)
        includes_tax: true,
      },
      description: "Gift card for recipient@example.com",
      // Store recipient info in metadata for order processing
      metadata: {
        recipient_email: "recipient@example.com",
        gift_card_type: "digital",
        delivery_method: "email",
      },
    },
  },
});
```

### Example: Adding a Donation

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

const cartId = getCartId();

// Add a donation directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "custom_item",
      name: "Donation - Save the Forests",
      sku: "donation-save-the-forests",
      quantity: 1,
      price: {
        amount: 1000, // $10 in minor units (cents)
        includes_tax: true,
      },
      description: "Donation to Save the Forests Foundation",
    },
  },
});
```

## Adding Subscription Items

You can add subscription products to a cart by specifying the subscription offering and plan:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

const cartId = getCartId();

// Add a subscription item to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "subscription_item",
      id: "5b9be99f-1c94-4ddd-9718-81adab0cc3e0", // Subscription offering ID
      quantity: 1,
      subscription_configuration: {
        plan: "40010dde-2f38-489b-8b3f-14a13cbfb431", // Plan ID
      },
    },
  },
});
```

The price of the subscription item in the cart reflects the cost of the subscription's initial billing period. Once the cart has been checked out and the order paid for, the subscription will be automatically created in the subscriptions service.

## Adding Promotion Codes

You can apply promotions to a cart using promotion codes:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

const cartId = getCartId();

// Add a promotion code to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "promotion_item",
      code: "SUMMER25",
    },
  },
});
```

## Adding Dynamic Bundles

Dynamic bundles allow customers to select from predefined component options. First, shoppers configure their bundle, then you add that configuration to the cart:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

const cartId = getCartId();

// Add a dynamic bundle with selected components to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "cart_item",
      id: "bundle-product-12345", // Bundle product ID
      quantity: 1,
      bundle_configuration: {
        selected_options: {
          "t-shirts": {
            // Component ID
            "red-shirt-id": 1, // Option ID and quantity
            "blue-shirt-id": 2, // Option ID and quantity
          },
          accessories: {
            "hat-id": 1,
          },
        },
      },
    },
  },
});
```

To include component product details in the response, you can use the `include` parameter:

```javascript
// When fetching the cart, include component product details
const cartResponse = await getCart({
  path: {
    cartID: cartId,
  },
  query: {
    include: ["items", "component_products"],
  },
});
```

## Adding Personalized Products

You can add products with custom text inputs for personalization:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

const cartId = getCartId();

// Add a personalized product to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "cart_item",
      id: "tshirt-product-id",
      quantity: 1,
      custom_inputs: {
        front: "Happy Birthday Dad!",
        back: "From your favorite child",
      },
    },
  },
});
```

Note that products with different `custom_inputs` values will be added as separate line items, even if they are the same product.

## Re-ordering from Previous Orders

You can help customers re-add items from previous orders to their current cart:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

const cartId = getCartId();
const orderId = "order-12345";

// Re-order items from a previous order
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "reorder",
      id: orderId,
    },
  },
});
```

## Cart Limitations and Best Practices

- A cart can contain a maximum of 100 unique items
- Items include products, custom items, tax items, and promotions
- For custom items, include a unique SKU to properly identify them
- The cart currency is set when the first item is added to the cart
- All products must have prices in the same currency as the cart

## Response Handling

The response contains the updated cart items:

```javascript
// Example response handling in a React component
const [isAddingToCart, setIsAddingToCart] = useState(false);
const [successMessage, setSuccessMessage] = useState("");
const [cartCount, setCartCount] = useState(0);

const handleAddToCart = async (productId) => {
  setIsAddingToCart(true);

  try {
    const result = await addToCart(productId);

    // Show success message
    setSuccessMessage(`Item added to your cart`);

    // Update cart count
    setCartCount(result.data.relationships.items.data.length);

    // Optionally refetch cart data to update UI
    await fetchCart();
  } catch (error) {
    setErrorMessage(error.message || "Failed to add item to cart");
  } finally {
    setIsAddingToCart(false);
  }
};
```

## Common Implementation Patterns

- **"Add to Cart" Button**: The most common implementation that adds a single item to the cart

```jsx
<button
  onClick={() => product.id && handleAddToCart(product.id)}
  disabled={isAddingToCart}
  className="bg-blue-500 hover:bg-blue-600 text-white py-2 px-3 rounded"
>
  {isAddingToCart ? "Adding..." : "Add to Cart"}
</button>
```

- **Quick-add functionality**: Add items directly from product listings
- **Add with options**: Include product variants or customizations when adding to cart

## Error Handling

- Out-of-stock scenarios: Check inventory before adding or handle API errors
- Invalid product IDs: Ensure the product exists before attempting to add
- Quantity restriction violations: Handle minimum and maximum quantity constraints

:::tip
For more detailed information about adding different types of items to a cart, see the [Elastic Path API documentation](https://elasticpath.dev/docs/api/carts/manage-carts).
:::

:::tip
For a complete implementation example, check out the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) in the Elastic Path Composable Frontend repository.
:::

---

## Apply Discount / Promo Code


This guide explains how to apply promotional discounts and coupon codes to a shopping cart in Elastic Path.

## Using the manageCarts SDK Method for Promotions

The `manageCarts` method can be used to apply discount codes to a cart:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

// Apply a promotion code to the cart
const applyPromotion = async (code) => {
  // Validate the promotion code
  if (!code.trim()) {
    throw new Error("Please enter a promotion code");
  }

  // Get the current cart ID
  const cartId = getCartId();
  if (!cartId) {
    throw new Error("Cart not found");
  }

  // Apply the promotion code
  const response = await manageCarts({
    path: {
      cartID: cartId,
    },
    body: {
      data: {
        type: "promotion_item",
        code: code.trim(),
      },
    },
  });

  return response.data;
};
```

## Removing Discount Codes

Use the `deleteAPromotionViaPromotionCode` method to remove an applied discount:

```javascript
import {
  deleteAPromotionViaPromotionCode,
  getCartId,
} from "@epcc-sdk/sdks-shopper";

// Remove a promotion from the cart
const removePromotion = async (code) => {
  // Get the current cart ID
  const cartId = getCartId();
  if (!cartId) {
    throw new Error("Cart not found");
  }

  // Remove the promotion
  await deleteAPromotionViaPromotionCode({
    path: {
      cartID: cartId,
      promoCode: code,
    },
  });

  return { success: true };
};
```

## Handling Promotion Updates in Your UI

```javascript
// Example of applying a promotion code with state updates
const [promoCode, setPromoCode] = useState("");
const [applyingPromo, setApplyingPromo] = useState(false);
const [promoError, setPromoError] = useState(null);
const [successMessage, setSuccessMessage] = useState("");

const handleApplyPromotion = async (code) => {
  setApplyingPromo(true);
  setPromoError(null);

  try {
    await applyPromotion(code);

    // Clear the input
    setPromoCode("");

    // Fetch updated cart to refresh UI with new promotions
    await fetchCart();

    // Show success message
    setSuccessMessage(`Promotion "${code}" applied successfully`);
  } catch (error) {
    setPromoError(error.message);
  } finally {
    setApplyingPromo(false);
  }
};

// Example of removing a promotion code
const [removingPromo, setRemovingPromo] = useState(false);

const handleRemovePromotion = async (code) => {
  setRemovingPromo(true);

  try {
    await removePromotion(code);

    // Fetch updated cart to refresh UI
    await fetchCart();

    // Show success message
    setSuccessMessage(`Promotion removed`);
  } catch (error) {
    setPromoError("Failed to remove promotion");
  } finally {
    setRemovingPromo(false);
  }
};
```

## Common UI Patterns

Promo code implementation in a cart UI:

```jsx
// Promotion code input and apply button

  <label className="block text-sm font-medium text-gray-700 mb-1">
    Promotion Code
  </label>
  
    <input
      type="text"
      value={promoCode}
      onChange={(e) => setPromoCode(e.target.value)}
      className="flex-grow px-3 py-2 border border-gray-300 rounded-l-md focus:ring-blue-500 focus:border-blue-500"
      placeholder="Enter code"
      disabled={applyingPromo}
    />
    <button
      onClick={() => handleApplyPromotion(promoCode)}
      disabled={!promoCode.trim() || applyingPromo}
      className="bg-blue-500 text-white px-4 py-2 rounded-r-md hover:bg-blue-600 disabled:bg-blue-300"
    >
      {applyingPromo ? "Applying..." : "Apply"}
    </button>
  
  {promoError && {promoError}}
;

{
  /* Display applied promotions */
}
{
  activePromotions.length > 0 && (
    
      Applied Promotions
      
        {activePromotions.map((promo) => (
          
            {promo.name || promo.id}
            <button
              onClick={() => handleRemovePromotion(promo.promotion_id)}
              className="text-sm text-red-500 hover:text-red-700"
              disabled={removingPromo}
            >
              Remove
            </button>
          
        ))}
      
    
  );
}
```

## Discount Stacking

Understanding how multiple discounts interact:

- Stacking rules: Whether multiple promotions can be applied together
- Discount precedence: How the system prioritizes competing discounts
- Maximum discount limitations: Caps on total discount amounts

## Integration with Promotions Service

- How the cart service connects with the promotions system
- Automatic vs. manual promotions

:::tip
For a fully functional implementation of promotion code handling, see the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) on GitHub.
:::

---

## Create & Retrieve a Cart


This guide explains how to create new shopping carts and retrieve existing ones in your Elastic Path implementation.

## Using the initializeCart Utility

The SDK provides a built-in `initializeCart` utility that simplifies cart creation and retrieval:

```javascript
import { initializeCart, getCartId } from "@epcc-sdk/sdks-shopper";

// Get or create a cart ID using the default storage key
const cartId = await initializeCart();

// Get cart ID without creating one (must use same storage key as initializeCart)
const existingCartId = getCartId();

// Use a custom storage key
const cartIdWithCustomKey = await initializeCart({
  storageKey: "my-custom-cart-key",
});

// When retrieving a cart ID that was stored with a custom key,
// you must use the same custom key
const retrievedCartId = getCartId({
  storageKey: "my-custom-cart-key",
});
```

### How initializeCart Works

The utility handles the entire cart initialization flow:

1. Checks localStorage for an existing cart ID using the specified key (or default key)
2. If a cart ID exists, returns it immediately
3. If no cart ID exists, creates a new cart via the API
4. Stores the new cart ID in localStorage with the specified key
5. Returns the cart ID as a string

This approach is perfect for implementing guest checkout flows and ensuring the shopper always has an active cart.

### Important Note on Storage Keys

When using `getCartId`, you must provide the same storage key that was used with `initializeCart`:

- If you called `initializeCart()` without a custom key, use `getCartId()` without a custom key
- If you called `initializeCart({ storageKey: "custom-key" })`, you must use `getCartId({ storageKey: "custom-key" })`

Using different keys will result in `getCartId` returning `null` even if a cart exists.

## Manual Cart Creation

If you need more control over the cart creation process, you can use the `manageCarts` SDK method directly:

```javascript
import { manageCarts } from "@epcc-sdk/sdks-shopper";

// Create a new cart
const response = await manageCarts({
  path: {
    cartID: "create",
  },
  body: {
    data: {},
  },
});

// Store the cart ID for later use
const cartId = response.data.data.id;
localStorage.setItem("ep_cart_id", cartId);
```

### Configuration Options

Key parameters when creating a cart:

- Currency settings: Specify the currency for the cart
- Store association: Associate the cart with a specific store
- Customer association: Link the cart to an authenticated user

## Extending Carts with Custom Data

You can enhance carts with additional data to support custom business requirements. There are three ways to extend cart data:

### 1. Using Cart Meta Data

Meta data allows you to attach custom key-value pairs to a cart:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

// Get the current cart ID
const cartId = getCartId();

// Add meta data directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      meta: {
        source: "mobile_app",
        campaign_id: "summer_sale_2023",
        utm_source: "email",
        custom_notes: "Customer requested gift wrapping",
      },
    },
  },
});
```

### 2. Creating Custom Cart Attributes

For structured custom data, you can use custom attributes:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

// Get the current cart ID
const cartId = getCartId();

// Add custom attributes directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "cart",
      id: cartId,
      custom_attributes: {
        delivery_instructions: "Leave at side door",
        preferred_delivery_date: "2023-12-24",
        gift_message: "Happy Birthday Mom!",
        insurance_selected: true,
        shipping_preferences: {
          carrier: "fedex",
          speed: "overnight",
        },
      },
    },
  },
});
```

### 3. Cart Flow Fields

Cart flow fields let you store data for specific flow steps:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

// Get the current cart ID
const cartId = getCartId();

// Add flow fields directly to the cart
const response = await manageCarts({
  path: {
    cartID: cartId,
  },
  body: {
    data: {
      type: "cart",
      id: cartId,
      flow: {
        gift_options: {
          gift_wrap: true,
          gift_message: "Happy Birthday!",
          gift_from: "Your Secret Admirer",
        },
      },
    },
  },
});
```

### Best Practices for Extended Attributes

1. **Use meaningful keys**: Name attributes clearly to maintain code readability
2. **Keep it lightweight**: Store only what you need - avoid excessive data
3. **Consider persistence**: Some extended data may need to transfer to orders
4. **Be consistent**: Use the same attribute structure across your application
5. **Validate input**: Ensure attributes meet your schema requirements before storing

## Retrieving an Existing Cart

The `getCart` SDK method allows you to fetch an existing cart by its ID:

```javascript
import { getCart, getCartId } from "@epcc-sdk/sdks-shopper";

// Get cartId from localStorage using the same key used with initializeCart
const cartId = getCartId();

// Or with a custom storage key
// const cartId = getCartId({ storageKey: "my-custom-cart-key" });

// Retrieve the cart with items included
const response = await getCart({
  path: {
    cartID: cartId,
  },
  query: {
    include: ["items"],
  },
});

// Access the cart data
const cart = response.data;
```

### Use Cases

- Retrieving carts after page refresh to maintain shopping state
- Accessing saved carts for returning customers
- Integrating with checkout flows to process orders
- Retrieving cart information for display in mini-cart components

## Integration with React Components

Here's a concise pattern for integrating cart initialization in a React component:

```jsx
import React, { useEffect, useState } from "react";
import { getCart, initializeCart } from "@epcc-sdk/sdks-shopper";

function CartComponent() {
  const [cart, setCart] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  // Optional: Use a custom storage key
  const storageKey = "my-custom-cart-key";

  useEffect(() => {
    async function loadCart() {
      try {
        // Get or create cart ID (with optional custom storage key)
        const cartId = await initializeCart({
          storageKey, // Optional: Remove if using default key
        });

        // Fetch cart data
        const response = await getCart({
          path: { cartID: cartId },
          query: { include: ["items"] },
        });

        setCart(response.data);
      } catch (err) {
        setError("Failed to initialize cart");
      } finally {
        setLoading(false);
      }
    }

    loadCart();
  }, []);

  if (loading) return Loading cart...;
  if (error) return Error: {error};

  return (
    
      Your Cart
      {/* Render cart details */}
    
  );
}
```

:::tip
For a complete implementation example, check out the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) in the Elastic Path Composable Frontend repository.
:::

---

## Persist Cart Across Sessions


This guide explains how to maintain cart state when customers leave and return to your store.

## Built-in Persistence with initializeCart

The Elastic Path SDK provides a built-in utility called `initializeCart` that handles cart persistence automatically:

```javascript
import { initializeCart, getCartId } from "@epcc-sdk/sdks-shopper";

// Get or create a cart, automatically persisted in localStorage
const cartId = await initializeCart();

// Retrieve the cart ID without creating a new cart
const existingCartId = getCartId();

// Use custom storage key if needed
const cartIdWithCustomKey = await initializeCart({
  storageKey: "my-custom-cart-key",
});
```

The `initializeCart` utility:

1. Checks localStorage for an existing cart ID
2. Returns it if found
3. Creates a new cart via the API if not found
4. Automatically stores the new cart ID in localStorage
5. Returns the cart ID for immediate use

This is the recommended approach for most applications as it handles persistence seamlessly.

## Custom Client-Side Storage Options

For more control or specific use cases, you may want to implement your own persistence strategy:

### Using localStorage

A custom implementation using localStorage:

```javascript
import { manageCarts } from "@epcc-sdk/sdks-shopper";

// Cart ID storage key
const CART_ID_KEY = "ep_cart_id";

// Create a cart and persist the ID
const createAndPersistCart = async () => {
  // Create a new cart
  const response = await manageCarts({
    path: {
      cartID: "create",
    },
    body: {
      data: {},
    },
  });

  const cartId = response.data.data.id;

  // Store the cart ID in localStorage
  localStorage.setItem(CART_ID_KEY, cartId);

  return cartId;
};

// Get the persisted cart ID
const getCartId = () => {
  return localStorage.getItem(CART_ID_KEY);
};

// Helper to check if we have a stored cart
const hasStoredCart = () => {
  return !!getCartId();
};

// Remove the cart ID (e.g., after order completion)
const clearCartId = () => {
  localStorage.removeItem(CART_ID_KEY);
};
```

### Using Cookies

For multi-domain applications, cookies may be a better choice:

```javascript
import { Cookies } from "react-cookie";
import { manageCarts } from "@epcc-sdk/sdks-shopper";

// Initialize cookies
const cookies = new Cookies();

// Cart ID cookie name
const CART_ID_COOKIE = "ep_cart_id";

// Create a cart and persist the ID in a cookie
const createAndPersistCart = async () => {
  // Create a new cart
  const response = await manageCarts({
    path: {
      cartID: "create",
    },
    body: {
      data: {},
    },
  });

  const cartId = response.data.data.id;

  // Store the cart ID in a cookie (30 days expiration)
  cookies.set(CART_ID_COOKIE, cartId, {
    path: "/",
    maxAge: 30 * 24 * 60 * 60, // 30 days in seconds
    sameSite: "lax",
  });

  return cartId;
};

// Get the persisted cart ID
const getCartId = () => {
  return cookies.get(CART_ID_COOKIE);
};
```

## Comparison of Persistence Methods

| Method       | Pros                                        | Cons                                     | Best for                |
| ------------ | ------------------------------------------- | ---------------------------------------- | ----------------------- |
| Built-in SDK | Simplest implementation, handles edge cases | Less customizable                        | Most applications       |
| localStorage | Larger storage capacity, simpler API        | Not shared across domains, no expiration | Single-domain sites     |
| Cookies      | Works across subdomains, server accessible  | Size limitations, included in requests   | Multi-domain ecosystems |

## Security Considerations

- **Data minimization**: Store only what's necessary (cart ID, not full cart data)
- **No sensitive information**: Never store payment details or personal information
- **HTTPS only**: Ensure your site uses HTTPS to protect stored data

## Implementation for Different Platforms

- **React/Next.js**: Use `useState` and `useEffect` hooks with localStorage
- **Server-Side Rendering**: Access cookies on the server to maintain cart state
- **Mobile apps**: Use AsyncStorage (React Native) or equivalent native storage

```jsx
// Example React hook for cart persistence
function useCart() {
  const [cartId, setCartId] = useState(() => {
    // Initialize from localStorage (runs only on client)
    if (typeof window !== "undefined") {
      return localStorage.getItem(CART_ID_KEY) || null;
    }
    return null;
  });

  // Persist cart ID to localStorage when it changes
  useEffect(() => {
    if (cartId) {
      localStorage.setItem(CART_ID_KEY, cartId);
    } else {
      localStorage.removeItem(CART_ID_KEY);
    }
  }, [cartId]);

  return { cartId, setCartId };
}
```

:::tip
For a real-world implementation of cart persistence, see the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) on GitHub.
:::

---

## Remove Items from Cart


This guide explains how to remove product items from a customer's shopping cart.

You can remove standard cart items using the `deleteACartItem` method, or remove promotion items using the promotion code and the `deleteAPromotionViaPromotionCode` method.

## Using the deleteACartItem SDK Method

The `deleteACartItem` method provides a simple way to remove items from a cart:

```javascript
import { deleteACartItem, getCartId } from "@epcc-sdk/sdks-shopper";

// Remove an item from the cart
const removeCartItem = async (itemId) => {
  // Get the current cart ID
  const cartId = getCartId();
  if (!cartId) {
    throw new Error("Cart not found");
  }

  // Delete the cart item
  await deleteACartItem({
    path: {
      cartID: cartId,
      cartitemID: itemId,
    },
  });

  return { success: true };
};
```

## Implementation Considerations

- **Single vs. bulk removal**: Decide whether to allow removing individual items or multiple at once
- **Confirmation dialogs**: Consider asking for confirmation before removing items
- **Removal feedback**: Provide visual feedback when items are successfully removed

## Response Handling

The `deleteACartItem` method returns a minimal response on success:

```javascript
// Example handling of item removal in a React component
const [isRemoving, setIsRemoving] = useState(false);
const [successMessage, setSuccessMessage] = useState("");
const [errorMessage, setErrorMessage] = useState("");

const handleRemoveItem = async (itemId) => {
  setIsRemoving(true);

  try {
    await removeCartItem(itemId);

    // Show success message
    setSuccessMessage("Item removed from cart");

    // Fetch the updated cart to reflect changes
    await fetchCart();
  } catch (error) {
    setErrorMessage("Failed to remove item");
  } finally {
    setIsRemoving(false);
  }
};
```

## Common UI Patterns

Standard approaches for presenting removal options:

```jsx
// Example remove button for cart items
<button
  onClick={() => handleRemoveItem(item.id)}
  className="text-red-500 hover:text-red-700"
  disabled={isRemoving}
>
  {isRemoving ? "Removing..." : "Remove"}
</button>
```

Other common patterns include:

- X icon in mini-cart for quick removal
- Remove button in full cart page
- Clear cart functionality for removing all items at once

## Use Cases

- **Customer-initiated removal**: When a customer decides they no longer want an item
- **System-initiated removal**: When an item becomes unavailable or out of stock
- **Quantity-based removal**: Setting an item's quantity to zero often removes it automatically

:::tip
Check out the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) on GitHub for a complete implementation of cart item removal.
:::

---

## Calculate Totals & Tax


This guide explains how to calculate and display cart totals, including taxes, in your Elastic Path implementation.

## Using getCart for Totals Calculation

Cart totals information is included in the `meta.display_price` object when retrieving a cart with the `getCart` SDK method:

```javascript
import { getCart, getCartId } from "@epcc-sdk/sdks-shopper";

// Fetch cart with totals information
const fetchCart = async () => {
  const cartId = getCartId();
  if (!cartId) {
    throw new Error("No cart found");
  }

  const response = await getCart({
    path: {
      cartID: cartId,
    },
    query: {
      include: ["items"], // Include cart items in the response
    },
  });

  // Cart totals are available in meta.display_price
  return response.data;
};
```

## Available Pricing Fields

The cart response contains several pricing components. Here's a comprehensive overview of all available pricing fields:

| Field                        | Location                       | Description                                                       |
| ---------------------------- | ------------------------------ | ----------------------------------------------------------------- |
| `with_tax.amount`            | Cart `meta.display_price`      | Total cart value including tax, in minor units (e.g., cents)      |
| `with_tax.formatted`         | Cart `meta.display_price`      | Formatted total cart value including tax (e.g., "$99.99")         |
| `without_tax.amount`         | Cart `meta.display_price`      | Total cart value excluding tax, in minor units                    |
| `without_tax.formatted`      | Cart `meta.display_price`      | Formatted total cart value excluding tax                          |
| `without_discount.amount`    | Cart `meta.display_price`      | Subtotal before any discounts, in minor units                     |
| `without_discount.formatted` | Cart `meta.display_price`      | Formatted subtotal before any discounts                           |
| `discount.amount`            | Cart `meta.display_price`      | Total discount amount (negative value), in minor units            |
| `discount.formatted`         | Cart `meta.display_price`      | Formatted total discount amount                                   |
| `tax.amount`                 | Cart `meta.display_price`      | Total tax amount, in minor units                                  |
| `tax.formatted`              | Cart `meta.display_price`      | Formatted total tax amount                                        |
| `shipping.amount`            | Cart `meta.display_price`      | Shipping cost, in minor units (if applicable)                     |
| `shipping.formatted`         | Cart `meta.display_price`      | Formatted shipping cost (if applicable)                           |
| `item.unit.amount`           | Cart item `meta.display_price` | Price per unit before discounts, in minor units                   |
| `item.unit.formatted`        | Cart item `meta.display_price` | Formatted price per unit before discounts                         |
| `item.value.amount`          | Cart item `meta.display_price` | Total value for this item (unit price × quantity), in minor units |
| `item.value.formatted`       | Cart item `meta.display_price` | Formatted total value for this item                               |
| `item.discount.amount`       | Cart item `meta.display_price` | Discount amount for this item (negative value), in minor units    |
| `item.discount.formatted`    | Cart item `meta.display_price` | Formatted discount amount for this item                           |
| `item.discounted.amount`     | Cart item `meta.display_price` | Price after discount, in minor units                              |
| `item.discounted.formatted`  | Cart item `meta.display_price` | Formatted price after discount                                    |

## Calculation Methods

Elastic Path uses two calculation methods that affect how totals are calculated:

- **Simple method**: Discounts applied after tax, rounding at unit level
- **Line method**: Discounts applied before tax, rounding at line level

The default for stores created after February 2020 is the "line" method.

For details, see [Calculate Cart and Order Totals](/guides/How-To/Carts/calculate-totals).

## Tax Management

Elastic Path offers several approaches to handle taxes in your shopping cart implementation.

### Adding Tax Items to a Cart Item

Tax items are applied to specific cart items, not directly to the cart:

```javascript
import { addTaxItemToCart, getCartId } from "@epcc-sdk/sdks-shopper";

// Get the current cart ID
const cartId = getCartId();

// Add a tax item to a specific cart item
// Note: You must have an existing cart item to apply tax to
const cartItemId = "cart-item-12345"; // ID of an existing cart item

const response = await addTaxItemToCart({
  path: {
    cartID: cartId,
    cartitemID: cartItemId, // Required: ID of the cart item to apply tax to
  },
  body: {
    data: {
      type: "tax_item",
      name: "CA State Tax",
      jurisdiction: "California",
      code: "CA_STATE_TAX",
      rate: 0.0725, // 7.25%
    },
  },
});
```

#### Important Notes About Tax Items:

- Tax items must be applied to existing cart items
- You need the cart item ID (`cartitemID`) to apply a tax
- The tax rate is specified as a decimal (e.g., 0.0725 for 7.25%)

### Best Practices for Tax Management

1. **Determine tax strategy early**: Decide if you'll use Elastic Path's calculation or a third-party tax service
2. **Consider tax complexity**: Different jurisdictions have different tax rules and rates
3. **Keep tax rates updated**: Tax rates can change - ensure your system stays current
4. **Document tax decisions**: Maintain clear records of tax-related implementation choices
5. **Test across regions**: Verify tax calculations for different geographic locations

## Integrating with Cart Initialization

When calculating totals, it's important to ensure a cart exists first. You can use the SDK's built-in `initializeCart` utility:

```javascript
import { getCart, initializeCart } from "@epcc-sdk/sdks-shopper";

// Get cart totals, creating a cart if needed
const getCartTotals = async () => {
  // First ensure a cart exists using the SDK's initializeCart utility
  const cartId = await initializeCart();

  // Fetch cart with totals
  const response = await getCart({
    path: {
      cartID: cartId,
    },
    query: {
      include: ["items"],
    },
  });

  // Extract pricing information
  const pricing = response.data?.data?.meta?.display_price;
  if (!pricing) {
    return {
      subtotal: "$0.00",
      discount: "$0.00",
      tax: "$0.00",
      total: "$0.00",
    };
  }

  return {
    subtotal: pricing.without_discount?.formatted || "$0.00",
    discount: pricing.discount?.formatted || "$0.00",
    tax: pricing.tax?.formatted || "$0.00",
    total: pricing.with_tax?.formatted || "$0.00",
    hasDiscount: (pricing.discount?.amount || 0) < 0,
  };
};
```

For more details on cart initialization, see the Elastic Path documentation.

## Understanding Cart Total Components

The cart response contains several pricing components in the `meta.display_price` object:

```javascript
// Extract pricing information from cart response
const getCartPricing = (cart) => {
  if (!cart?.data?.meta?.display_price) return null;

  const pricing = cart.data.meta.display_price;

  return {
    // Total with tax included
    total: pricing.with_tax?.formatted || "$0.00",

    // Subtotal before discounts
    subtotal: pricing.without_discount?.formatted || "$0.00",

    // Discount amount (negative value)
    discount: pricing.discount?.formatted || "$0.00",

    // Tax amount
    tax: pricing.tax?.formatted || "$0.00",

    // Shipping cost
    shipping: pricing.shipping?.formatted || "$0.00",

    // Check if a discount has been applied
    hasDiscount: (pricing.discount?.amount || 0) < 0,
  };
};
```

## UI Implementation

Common patterns for displaying cart totals:

```jsx
// Cart totals display component
const CartTotals = ({ pricing }) => {
  if (!pricing) return null;

  return (
    
      Cart Summary

      
        
          Subtotal
          {pricing.subtotal}
        

        {pricing.hasDiscount && (
          
            Discount
            {pricing.discount}
          
        )}

        {pricing.shipping !== "$0.00" && (
          
            Shipping
            {pricing.shipping}
          
        )}

        
          Tax
          {pricing.tax}
        

        
          Total
          {pricing.total}
        
      
    
  );
};
```

## Special Considerations

- **B2B tax handling**: Business customers may have different tax requirements
- **International tax concerns**: Different regions have different tax rules
- **Tax exemption handling**: Some customers may be exempt from certain taxes

:::tip
For a real-world implementation of cart totals calculation that uses the `initializeCart` utility, see the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) on GitHub.
:::

---

## Update Item Quantities


This guide explains how to update the quantities of items already in a customer's shopping cart.

## Using the updateACartItem SDK Method

The `updateACartItem` method allows you to modify existing cart line items:

```javascript
import { updateACartItem, getCartId } from "@epcc-sdk/sdks-shopper";

// Update item quantity in cart
const updateItemQuantity = async (itemId, newQuantity) => {
  // If quantity is less than 1, consider removing the item instead
  if (newQuantity < 1) {
    // Handle item removal (see the "Remove Items from Cart" guide)
    return;
  }
  // Get the current cart ID
  const cartId = getCartId();
  if (!cartId) {
    throw new Error("Cart not found");
  }

  // Update the item quantity
  const response = await updateACartItem({
    path: {
      cartID: cartId,
      cartitemID: itemId,
    },
    body: {
      data: {
        id: itemId,
        quantity: newQuantity,
      },
    },
  });

  return response.data;
};
```

## Key Functionality

- **Increasing quantities**: Add more of an item to the cart
- **Decreasing quantities**: Reduce the number of an item in the cart
- **Zero quantity**: Setting quantity to zero typically removes the item

## Implementation Examples

Common UI patterns for quantity updates include increment/decrement buttons:

```jsx

  <button
    onClick={() => updateItemQuantity(item.id, currentQuantity - 1)}
    disabled={isUpdating || currentQuantity <= 1}
    className="px-2 py-1 text-gray-600 hover:bg-gray-100 disabled:opacity-50"
    aria-label="Decrease quantity"
  >
    <svg
      className="w-4 h-4"
      fill="none"
      stroke="currentColor"
      viewBox="0 0 24 24"
    >
      <path
        strokeLinecap="round"
        strokeLinejoin="round"
        strokeWidth={2}
        d="M20 12H4"
      />
    </svg>
  </button>
  
    {isUpdating ? "..." : currentQuantity}
  
  <button
    onClick={() => updateItemQuantity(item.id, currentQuantity + 1)}
    disabled={isUpdating}
    className="px-2 py-1 text-gray-600 hover:bg-gray-100 disabled:opacity-50"
    aria-label="Increase quantity"
  >
    <svg
      className="w-4 h-4"
      fill="none"
      stroke="currentColor"
      viewBox="0 0 24 24"
    >
      <path
        strokeLinecap="round"
        strokeLinejoin="round"
        strokeWidth={2}
        d="M12 4v16m8-8H4"
      />
    </svg>
  </button>

```

## Response Handling

The response contains the updated cart with new quantity information:

```javascript
// Example component for handling quantity updates
const [updatingItems, setUpdatingItems] = useState({});
const [error, setError] = useState(null);

const handleQuantityUpdate = async (itemId, newQuantity) => {
  // Set updating state for this specific item
  setUpdatingItems((prev) => ({ ...prev, [itemId]: true }));

  try {
    await updateItemQuantity(itemId, newQuantity);

    // Fetch updated cart data to refresh UI
    await fetchCart();
  } catch (error) {
    setError("Failed to update quantity");
  } finally {
    // Clear updating state for this item
    setUpdatingItems((prev) => ({ ...prev, [itemId]: false }));
  }
};
```

## Error Handling

- Maximum quantity limits: Prevent exceeding allowed quantities
- Minimum quantity requirements: Enforce minimum order amounts
- Inventory restrictions: Check available stock before updating

:::tip
For a working implementation of quantity updates, see the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) on GitHub.
:::

---

## Overview(Cart)

# Cart Basics

This document explains the fundamental concepts of cart management in Elastic Path Commerce Cloud.

## Cart Data Model

The cart system consists of two primary entities:

- **Cart** - The parent container for all items a customer wants to purchase
- **Cart Line** - Individual product items within the cart, represented as cart_item objects

Each cart has the following key attributes:

- Unique ID for identification
- Relationships to items (products)
- Optional customer association
- Currency and pricing information
- Meta data including display pricing

## ID Conventions

Cart IDs are unique identifiers that are used to retrieve and manipulate cart data:

```javascript
// Example cart ID structure
"cart_id": "12345678-1234-1234-1234-123456789012"
```

Cart IDs are typically stored in localStorage or cookies for persistence across page reloads and sessions.

## Anonymous Carts

Anonymous carts allow visitors to shop before signing in. Key features include:

- Created without requiring user authentication
- Can be merged with a user's cart upon login
- Persist based on browser storage mechanisms
- Retrieved using the `getCart` SDK method with the cart ID

## Merge Rules

When a user logs in with an existing anonymous cart, the following merge rules apply:

- Carts must share the same currency and store to be eligible for merging
- When currencies match, items from the anonymous cart are added to the user's cart
- Line items with the same product are typically combined and quantities summed
- Promotions are re-evaluated after merging

## Key Considerations for Architects

- Design your cart state management to persist cart IDs between sessions
- Implement cart recovery strategies for abandoned carts
- Create intuitive cart merge behaviors for a seamless shopping experience
- Plan for inventory validation at key cart touchpoints

:::tip
For a complete implementation example demonstrating these cart concepts, check out the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) on GitHub.
:::

---

## Quick Start(Cart)

# Cart Management Quick Start

This quick-start guide walks you through the essential steps for implementing a complete cart lifecycle in your Elastic Path storefront application.

## Prerequisites

- A JavaScript application with Elastic Path SDK installed
- `@epcc-sdk/sdks-shopper` package configured with your client credentials

```bash
npm install @epcc-sdk/sdks-shopper
```

## Step 1: Initialize the Cart

The first step is to either create a new cart or retrieve an existing one using the SDK's built-in `initializeCart` utility:

```javascript
import { initializeCart } from "@epcc-sdk/sdks-shopper";

// Get or create a cart ID
const cartId = await initializeCart();
```

This utility handles both first-time visitors and returning customers by checking for a previously stored cart ID.

## Step 2: Add Items to Cart

Add products to the cart using the `manageCarts` method:

```javascript
import { manageCarts, getCartId } from "@epcc-sdk/sdks-shopper";

// Add a product to cart
const addToCart = async (productId, quantity = 1) => {
  const cartId = getCartId();

  if (!cartId) {
    throw new Error("No cart found");
  }

  const response = await manageCarts({
    path: {
      cartID: cartId,
    },
    body: {
      data: {
        type: "cart_item",
        id: productId,
        quantity: quantity,
      },
    },
  });

  return response.data;
};
```

## Step 3: Update Item Quantities

Modify quantities of items already in the cart:

```javascript
import { updateACartItem, getCartId } from "@epcc-sdk/sdks-shopper";

// Update quantity of an item in the cart
const updateItemQuantity = async (itemId, newQuantity) => {
  const cartId = getCartId();

  if (!cartId) {
    throw new Error("Cart not found");
  }

  const response = await updateACartItem({
    path: {
      cartID: cartId,
      cartitemID: itemId,
    },
    body: {
      data: {
        id: itemId,
        quantity: newQuantity,
      },
    },
  });

  return response.data;
};
```

## Step 4: Calculate Cart Totals

Retrieve the cart with totals information:

```javascript
import { getCart, getCartId } from "@epcc-sdk/sdks-shopper";

// Get cart with totals
const getCartWithTotals = async () => {
  const cartId = getCartId();

  if (!cartId) {
    throw new Error("No cart found");
  }

  const response = await getCart({
    path: {
      cartID: cartId,
    },
    query: {
      include: ["items"], // Include cart items in the response
    },
  });

  // Extract pricing information
  const pricing = response.data?.data?.meta?.display_price;
  if (pricing) {
    console.log("Cart totals:", {
      subtotal: pricing.without_discount?.formatted,
      discount: pricing.discount?.formatted,
      tax: pricing.tax?.formatted,
      total: pricing.with_tax?.formatted,
    });
  }

  return response.data;
};
```

## Step 5: Place an Order

Complete the cart lifecycle by converting it to an order:

```javascript
import { checkoutACart, getCartId } from "@epcc-sdk/sdks-shopper";

// Checkout a cart to create an order
const placeOrder = async (customerData) => {
  const cartId = getCartId();

  if (!cartId) {
    throw new Error("No cart found");
  }

  const response = await checkoutACart({
    path: {
      cartID: cartId,
    },
    body: {
      data: {
        customer: customerData.customer,
        billing_address: customerData.billingAddress,
        shipping_address: customerData.shippingAddress,
      },
    },
  });

  // Clear the cart ID after successful order
  localStorage.removeItem("ep_cart_id");

  return response.data;
};
```

## Complete Cart Flow Example

Here's how you might implement a complete cart flow in a React component:

```jsx
import React, { useEffect, useState } from "react";
import { getCart, initializeCart, getCartId } from "@epcc-sdk/sdks-shopper";

function CartExample() {
  const [cart, setCart] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  // Fetch cart data from API
  const fetchCart = async () => {
    try {
      setLoading(true);
      const cartId = getCartId();

      if (!cartId) {
        setError("No cart found");
        return null;
      }

      const response = await getCart({
        path: { cartID: cartId },
        query: { include: ["items"] },
      });

      setCart(response.data);
      return response.data;
    } catch (err) {
      setError("Failed to fetch cart");
      console.error(err);
      return null;
    } finally {
      setLoading(false);
    }
  };

  // Initialize or fetch cart on component mount
  useEffect(() => {
    const loadCart = async () => {
      try {
        setLoading(true);

        // Use the SDK's initializeCart utility
        const cartId = await initializeCart();

        // Fetch full cart data
        const response = await getCart({
          path: { cartID: cartId },
          query: { include: ["items"] },
        });

        setCart(response.data);
      } catch (err) {
        setError("Failed to initialize cart");
        console.error(err);
      } finally {
        setLoading(false);
      }
    };

    loadCart();
  }, []);

  // Add product to cart
  const handleAddToCart = async (productId, quantity = 1) => {
    try {
      setLoading(true);
      await addToCart(productId, quantity);
      await fetchCart(); // Refresh cart data
    } catch (err) {
      setError("Failed to add product");
    } finally {
      setLoading(false);
    }
  };

  // Update item quantity
  const handleUpdateQuantity = async (itemId, quantity) => {
    try {
      setLoading(true);
      await updateItemQuantity(itemId, quantity);
      await fetchCart(); // Refresh cart data
    } catch (err) {
      setError("Failed to update quantity");
    } finally {
      setLoading(false);
    }
  };

  return (
    
      {/* Cart UI implementation */}
      {loading && Loading...}
      {error && Error: {error}}
      {cart && (
        
          Your Cart
          {/* Render cart items and totals */}
        
      )}
    
  );
}
```

## Next Steps

Now that you've implemented a basic cart lifecycle, explore these advanced topics:

- [Cart Basics](./overview) - Understand cart data models and concepts
- [Create & Retrieve a Cart](./how-to/create-cart) - Learn more about cart initialization
- [Add Items to Cart](./how-to/add-items) - Learn about adding different types of items
- [Apply Promotions](./how-to/apply-promotions) - Add discount codes to carts
- [Remove Items from Cart](./how-to/remove-items) - Learn how to remove items
- [Update Quantities](./how-to/update-quantities) - Modify item quantities
- [Calculate Totals & Tax](./how-to/totals-tax) - Display pricing information
- [Cart Persistence](./how-to/persistence) - Implement advanced persistence strategies

:::tip
For a complete example, check out the [SPA Cart Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-cart) in the Elastic Path Composable Frontend repository.
:::

---

## Cleanup a Cart After Checkout

# Cart Cleanup After Checkout

This guide explains how to handle cart cleanup after successful checkout, including understanding cart persistence and implementing appropriate cleanup strategies.

## Cart Persistence and Implications

In Elastic Path, carts persist even after an order has been created. This persistence has several implications to be aware of:

- **Stale carts** - Without cleanup, customers may return to carts with outdated items
- **User experience** - Customers could see previously purchased items still in their cart

Understanding cart persistence allows you to implement appropriate cleanup strategies that align with your business needs.

## Cart Cleanup Options

### Local Storage Cleanup

When using browser storage to track cart IDs, you should clear this storage after successful checkout:

```javascript
// Clear cart ID from local storage
function clearLocalCart() {
  // if you used a custom key on cart creation, use it here.
  localStorage.removeItem("ep_cart_id");
}
```

### API Cart Cleanup

The Elastic Path Shopper SDK provides methods to delete carts via the API:

```javascript
import { deleteACart } from "@epcc-sdk/sdks-shopper";

// Delete a cart using the Shopper SDK
async function deleteCartFromAPI(cartId) {
  try {
    const response = await deleteACart({
      path: {
        cartID: cartId,
      },
    });

    console.log("Cart successfully deleted");
    return true;
  } catch (error) {
    console.error("Failed to delete cart:", error);
    return false;
  }
}
```

### Comprehensive Cart Cleanup

For a complete cleanup solution, you could implement both local and API cleanup:

```javascript
import { deleteACart } from "@epcc-sdk/sdks-shopper";

// Complete cart cleanup after successful checkout
async function cleanupAfterCheckout(cartId) {
  // First try to delete the cart from the API
  try {
    await deleteACart({
      path: {
        cartID: cartId,
      },
    });
    console.log("Cart successfully deleted from API");
  } catch (error) {
    console.error("Failed to delete cart from API:", error);
  }

  // Always clear local storage regardless of API success
  localStorage.removeItem("ep_cart_id");

  console.log("Local cart data cleared");
}
```

## Next Steps

- [Order Confirmation](./order-confirmation)
- [Cart Cleanup](./cleanup-carts)
- [Guest Checkout](./guest-checkout)

---

## Checkout a Known Customer

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# Customer Checkout

This guide explains how to convert a cart to an order using existing customer records, accounts, or account authentication tokens in Elastic Path Commerce.

## Setup

Install and configure the Shopper SDK:

```bash
npm install @epcc-sdk/sdks-shopper
```

## Checkout Options

Choose the checkout method that best fits your use case:

<Tabs>
<TabItem value="account" label="Account Checkout" default>

Use this approach for D2C storefronts and B2B scenarios where you need to associate orders with organizational accounts.

### Authentication Setup

First, obtain an account management authentication token. Typically, this is done by allowing the user to login:

```javascript
import { postV2AccountMembersTokens } from "@epcc-sdk/sdks-shopper";

async function loginAccountMember(username, password) {
  try {
    const response = await postV2AccountMembersTokens({
      body: {
        data: {
          type: "account_management_authentication_token",
          authentication_mechanism: "password",
          username: username,
          password: password,
        },
      },
    });

    const authToken = response.data?.data?.token;
    if (!authToken) {
      throw new Error("Authentication failed");
    }

    // Store securely
    localStorage.setItem("ep_account_management_token", authToken);
    return authToken;
  } catch (error) {
    console.error("Login failed:", error);
    throw error;
  }
}
```

### Implementation

Provide the token as the `EP-Account-Management-Authentication-Token` header on the checkout request:

```javascript
import {
  getCartId,
  checkoutApi,
  getV2AccountAddresses,
} from "@epcc-sdk/sdks-shopper";

async function checkoutWithAuthToken(contactInfo) {
  try {
    const cartId = getCartId();
    if (!cartId) {
      throw new Error("No cart found. Please add items to your cart first.");
    }

    // Optionally fetch saved addresses for the account
    const savedAddresses = await getV2AccountAddresses({
      path: { accountID: accountId },
    });

    // Create checkout data
    const checkoutData = {
      data: {
        contact: contactInfo,
        billing_address: savedAddresses.billing,
        shipping_address: savedAddresses.shipping,
      },
    };

    // Retrieve the stored token
    const authToken = localStorage.getItem("ep_account_management_token");

    // Checkout with authentication token
    const checkoutResponse = await checkoutApi({
      path: {
        cartID: cartId,
      },
      body: checkoutData,
      headers: {
        "EP-Account-Management-Authentication-Token": authToken,
      },
    });

    return checkoutResponse.data;
  } catch (error) {
    console.error("Authenticated checkout failed:", error);
    throw error;
  }
}
```

</TabItem>
<TabItem value="customer-id" label="Customer ID Checkout">

Use this approach when you have an existing customer record and want to streamline the checkout process without account association.

### Implementation

```javascript
import { getCartId, checkoutApi, paymentSetup } from "@epcc-sdk/sdks-shopper";

async function checkoutWithCustomerId(customerId, shippingAddress) {
  try {
    const cartId = getCartId();
    if (!cartId) {
      throw new Error("No cart found. Please add items to your cart first.");
    }

    // Create checkout data with customer ID
    const checkoutData = {
      data: {
        customer: {
          id: customerId,
        },
        shipping_address: shippingAddress,
        // Optionally add billing address
        billing_address: {
          first_name: "John",
          last_name: "Doe",
          line_1: "123 Billing St",
          city: "Billing City",
          postcode: "12345",
          country: "US",
        },
      },
    };

    // Checkout the cart
    const checkoutResponse = await checkoutApi({
      path: {
        cartID: cartId,
      },
      body: checkoutData,
    });

    return checkoutResponse.data;
  } catch (error) {
    console.error("Customer ID checkout failed:", error);
    throw error;
  }
}
```

</TabItem>
</Tabs>

## Best Practices

1. **Address Management**: Consider using saved addresses with `getV2AccountAddresses` for better UX
2. **Error Handling**: Implement comprehensive error handling for network issues and validation
3. **Security**: Store authentication tokens securely and implement refresh logic
4. **Validation**: Validate all form inputs before submission
5. **Loading States**: Provide clear feedback during checkout process

## Next Steps

- [Guest Checkout](./guest-checkout)
- [Implement Card Payments](../payments/elastic-path-payments/implement-payments)
- [Order Confirmation](./order-confirmation)
- [Cart Cleanup](./cleanup-carts)

---

## Checkout a Guest

# Guest Checkout

This guide explains how to implement guest checkout using a customer object.

## Prerequisites

- An Elastic Path Commerce store
- API client credentials with appropriate permissions
- A cart with items
- `@epcc-sdk/sdks-shopper` package installed

## Implementation Steps

1. **Install and Configure the Shopper SDK**

   ```bash
   npm install @epcc-sdk/sdks-shopper
   ```

2. **Create a Checkout Form**

   - Build a form to collect essential customer information (name, email, billing and shipping addresses)
   - Include any necessary validation to ensure data quality

3. **Format the Customer Data Object**

   - Structure the collected form data as a customer object
   - Include customer details, billing address, and shipping address

   ```javascript
   // Basic structure of a guest checkout object
   const checkoutData = {
     data: {
       // Optional fields
       order_number: 1234,
       external_ref: "order-ref-123",

       // Customer information (required)
       customer: {
         email: "john@example.com",
         name: "John Doe",
       },

       // Billing address
       billing_address: {
         first_name: "John",
         last_name: "Doe",
         company_name: "Company Inc",
         line_1: "123 Billing St",
         line_2: "Suite 101",
         city: "Billing City",
         county: "Billing County",
         region: "State",
         postcode: "12345",
         country: "US",
       },

       // Shipping address
       shipping_address: {
         first_name: "John",
         last_name: "Doe",
         phone_number: "(555) 555-1234",
         company_name: "Company Inc",
         line_1: "123 Shipping St",
         line_2: "Apt 202",
         city: "Shipping City",
         county: "Shipping County",
         region: "State",
         postcode: "12345",
         country: "US",
         instructions: "Leave package at front door",
       },
     },
   };
   ```

4. **Convert Cart to Order**

   - Use the `checkoutApi` function to convert the cart to an order
   - Pass the customer data object as part of the request

5. **Process Payment**

   - Implement a payment processing solution
   - For simple testing, you can use the manual gateway

6. **Display Order Confirmation**
   - Show order details to the customer
   - Clear the cart data after successful checkout

## Sample Implementation

Here's a simple React component implementing guest checkout:

```jsx
import React, { useState } from "react";
import { getCartId, checkoutApi, paymentSetup } from "@epcc-sdk/sdks-shopper";

function GuestCheckout() {
  // State for form data
  const [formData, setFormData] = useState({
    email: "",
    firstName: "",
    lastName: "",
    billingLine1: "",
    billingCity: "",
    billingPostcode: "",
    billingCountry: "",
    shippingLine1: "",
    shippingCity: "",
    shippingPostcode: "",
    shippingCountry: "",
    sameAsShipping: true,
  });

  // State for tracking process
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  const [orderConfirmation, setOrderConfirmation] = useState(null);

  // Handle form input changes
  const handleInputChange = (e) => {
    const { name, value, type, checked } = e.target;
    setFormData((prev) => ({
      ...prev,
      [name]: type === "checkbox" ? checked : value,
    }));
  };

  // Handle form submission
  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    setError(null);

    try {
      // Create customer data object for checkout
      const customerData = {
        customer: {
          email: formData.email,
          name: `${formData.firstName} ${formData.lastName}`,
        },
        billing_address: {
          first_name: formData.firstName,
          last_name: formData.lastName,
          line_1: formData.billingLine1,
          city: formData.billingCity,
          postcode: formData.billingPostcode,
          country: formData.billingCountry,
        },
        shipping_address: {
          first_name: formData.firstName,
          last_name: formData.lastName,
          line_1: formData.sameAsShipping
            ? formData.billingLine1
            : formData.shippingLine1,
          city: formData.sameAsShipping
            ? formData.billingCity
            : formData.shippingCity,
          postcode: formData.sameAsShipping
            ? formData.billingPostcode
            : formData.shippingPostcode,
          country: formData.sameAsShipping
            ? formData.billingCountry
            : formData.shippingCountry,
        },
      };

      // Get cart ID
      const cartId = getCartId();
      if (!cartId) {
        throw new Error("No cart found. Please add items to your cart first.");
      }

      // Checkout the cart
      const checkoutResponse = await checkoutApi({
        path: {
          cartID: cartId,
        },
        body: {
          data: customerData,
        },
      });

      const orderId = checkoutResponse.data?.data?.id;
      if (!orderId) {
        throw new Error("Failed to create order");
      }

      // Process payment using manual gateway
      const paymentResponse = await paymentSetup({
        path: {
          orderID: orderId,
        },
        body: {
          data: {
            gateway: "manual",
            method: "purchase",
          },
        },
      });

      // Set order confirmation details
      setOrderConfirmation({
        orderId: paymentResponse.data?.data?.order?.id,
        orderReference: paymentResponse.data?.data?.order?.reference,
        orderStatus: paymentResponse.data?.data?.order?.status,
        orderTotal:
          paymentResponse.data?.data?.order?.meta?.display_price?.with_tax
            ?.formatted,
      });
    } catch (err) {
      setError(err.message || "Checkout failed. Please try again.");
      console.error("Checkout error:", err);
    } finally {
      setLoading(false);
    }
  };

  // Show order confirmation if checkout was successful
  if (orderConfirmation) {
    return (
      
        Thank you for your order!
        Order ID: {orderConfirmation.orderId}
        Reference: {orderConfirmation.orderReference}
        Status: {orderConfirmation.orderStatus}
        Total: {orderConfirmation.orderTotal}
      
    );
  }

  // Render checkout form
  return (
    <form onSubmit={handleSubmit} className="checkout-form">
      Guest Checkout
      {error && {error}}

      
        Contact Information
        
          <label htmlFor="email">Email</label>
          <input
            type="email"
            id="email"
            name="email"
            value={formData.email}
            onChange={handleInputChange}
            required
          />
        
        
          
            <label htmlFor="firstName">First Name</label>
            <input
              type="text"
              id="firstName"
              name="firstName"
              value={formData.firstName}
              onChange={handleInputChange}
              required
            />
          
          
            <label htmlFor="lastName">Last Name</label>
            <input
              type="text"
              id="lastName"
              name="lastName"
              value={formData.lastName}
              onChange={handleInputChange}
              required
            />
          
        
      

      
        Billing Address
        
          <label htmlFor="billingLine1">Address</label>
          <input
            type="text"
            id="billingLine1"
            name="billingLine1"
            value={formData.billingLine1}
            onChange={handleInputChange}
            required
          />
        
        
          <label htmlFor="billingCity">City</label>
          <input
            type="text"
            id="billingCity"
            name="billingCity"
            value={formData.billingCity}
            onChange={handleInputChange}
            required
          />
        
        
          
            <label htmlFor="billingPostcode">Postal Code</label>
            <input
              type="text"
              id="billingPostcode"
              name="billingPostcode"
              value={formData.billingPostcode}
              onChange={handleInputChange}
              required
            />
          
          
            <label htmlFor="billingCountry">Country</label>
            <input
              type="text"
              id="billingCountry"
              name="billingCountry"
              value={formData.billingCountry}
              onChange={handleInputChange}
              required
            />
          
        
      

      
        <input
          type="checkbox"
          id="sameAsShipping"
          name="sameAsShipping"
          checked={formData.sameAsShipping}
          onChange={handleInputChange}
        />
        <label htmlFor="sameAsShipping">Shipping address same as billing</label>
      

      {!formData.sameAsShipping && (
        
          Shipping Address
          
            <label htmlFor="shippingLine1">Address</label>
            <input
              type="text"
              id="shippingLine1"
              name="shippingLine1"
              value={formData.shippingLine1}
              onChange={handleInputChange}
              required
            />
          
          
            <label htmlFor="shippingCity">City</label>
            <input
              type="text"
              id="shippingCity"
              name="shippingCity"
              value={formData.shippingCity}
              onChange={handleInputChange}
              required
            />
          
          
            
              <label htmlFor="shippingPostcode">Postal Code</label>
              <input
                type="text"
                id="shippingPostcode"
                name="shippingPostcode"
                value={formData.shippingPostcode}
                onChange={handleInputChange}
                required
              />
            
            
              <label htmlFor="shippingCountry">Country</label>
              <input
                type="text"
                id="shippingCountry"
                name="shippingCountry"
                value={formData.shippingCountry}
                onChange={handleInputChange}
                required
              />
            
          
        
      )}

      <button type="submit" disabled={loading} className="checkout-button">
        {loading ? "Processing..." : "Complete Checkout"}
      </button>
    </form>
  );
}

export default GuestCheckout;
```

## Next Steps

- [Checkout a customer](./customer-checkout)
- [Implement Card Payments](../payments/elastic-path-payments/implement-payments)
- [Order Confirmation](./order-confirmation)
- [Cart Cleanup](./cleanup-carts)

---

## Handle Account Addresses

# Working with Account Addresses

Account addresses allow users to save and reuse shipping or billing addresses during checkout. They are the recommended approach for most B2B and D2C storefronts, providing robust features and flexibility for authenticated users.

Account addresses are saved addresses associated with a registered customer account. They allow returning users to quickly select from previously used shipping or billing addresses during checkout, improving convenience and reducing friction. Managing account addresses is useful for B2B and D2C storefronts where users may want to save multiple addresses (e.g., home, work, office) and reuse them in future purchases.

## Prerequisites

- You have installed and configured the `@epcc-sdk/sdks-shopper` package.
- The user is authenticated and you have their account ID and Account Management Authentication Token.

## Setup

Install and configure the Shopper SDK:

```bash
npm install @epcc-sdk/sdks-shopper
```

## Common Use Cases

- Let a returning user select a shipping or billing address during checkout.
- Allow a user to add a new address to their account for future use.
- Set a default address for an account.

## Retrieve Saved Addresses for an Account

Use the SDK to fetch all addresses for an account. This is useful for letting a returning user select a shipping or billing address during checkout.

```javascript
import { getV2AccountAddresses } from "@epcc-sdk/sdks-shopper";

async function fetchAccountAddresses(accountId, accountToken) {
  const response = await getV2AccountAddresses({
    path: { accountID: accountId },
    headers: { "EP-Account-Management-Authentication-Token": accountToken },
  });
  return response.data?.data || [];
}
```

## Add a New Address to an Account

Allow the user to add a new address and save it to their account for future use.

```javascript
import { postV2AccountAddress } from "@epcc-sdk/sdks-shopper";

async function addAccountAddress(accountId, accountToken, addressData) {
  const response = await postV2AccountAddress({
    path: { accountID: accountId },
    body: { data: { type: "address", ...addressData } },
    headers: { "EP-Account-Management-Authentication-Token": accountToken },
  });
  return response.data?.data;
}
```

:::info

## Setting a Default Address

The Account Address service does not provide a direct way to set a default address for an account. If you want to support default addresses in your storefront, you can:

- Use the `name` field on the address (e.g., set it to "default") and filter for it in your UI.
- Track the user's preferred address ID in your application state or database.

When presenting address options to the user, you can highlight or pre-select the default address based on your chosen approach.
:::

## Next Steps

- [Guest Checkout](./guest-checkout) - Implement guest checkout flow
- [Customer Checkout](./customer-checkout) - Checkout with customer accounts
- [Provide Shipping Options](./manage-shipping) - Add shipping options to carts
- [Order Confirmation](./order-confirmation) - Display order confirmation details

---

## Provide Shipping Options

This guide explains how to implement flexible shipping options in your Elastic Path storefront using custom cart items. Custom cart items allow you to conveniently add shipping fees, delivery options, and special services that don't exist as products in your catalog at checkout.

## Understanding Custom Cart Items for Shipping

Custom cart items are perfect for shipping because they allow you to:

- Add shipping fees based on location, weight, or delivery speed, which may be specific to each cart
- Offer special delivery services (express, overnight, white-glove)
- Apply dynamic shipping costs from third-party APIs

:::warning
Custom Cart Items can be applied using an `implicit` token, so you should validate the contents of your orders.
:::

## Setup

Install and configure the Shopper SDK:

```bash
npm install @epcc-sdk/sdks-shopper
```

## Basic Shipping Implementation

### Apply Shipping to a Cart

```javascript
import { addCustomItemToCart, getCartId } from "@epcc-sdk/sdks-shopper";

async function addStandardShipping() {
  try {
    const cartId = getCartId();

    // You could also call out to a third party shipping API to get the shipping options
    const shippingItem = {
      type: "custom_item",
      name: "Standard Shipping",
      sku: "SHIP-STANDARD",
      description: "5-7 business days delivery",
      quantity: 1,
      price: {
        amount: 500,
      },
    };

    const response = await addCustomItemToCart({
      path: {
        cartID: cartId,
      },
      body: {
        data: shippingItem,
      },
    });

    console.log("Standard shipping added:", response.data);
    return response.data;
  } catch (error) {
    console.error("Failed to add shipping:", error);
    throw error;
  }
}
```

### Handle Shipping Updates

When users change shipping options, remove the old shipping item:

```javascript
import { removeCartItem } from "@epcc-sdk/sdks-shopper";

async function updateShippingOption(newShippingOption, currentShippingItemId) {
  try {
    const cartId = getCartId();

    // Remove current shipping
    if (currentShippingItemId) {
      await removeCartItem({
        path: {
          cartID: cartId,
          cartItemID: currentShippingItemId,
        },
      });
    }

    // Add new shipping
    await addCustomItemToCart({
      path: {
        cartID: cartId,
      },
      body: {
        data: newShippingOption,
      },
    });
  } catch (error) {
    console.error("Failed to update shipping:", error);
  }
}
```

## Next Steps

- [Shipping Groups](./shipping-groups) - For complex split shipping scenarios
- [Order Confirmation](./order-confirmation)
- [Guest Checkout](./guest-checkout)
- [Customer Checkout](./customer-checkout)

---

## Display an Order Confirmation

# Order Confirmation

This guide explains how to create effective order confirmation pages and manage order status updates after successful checkout.

## Understanding Order Data Flow in Elastic Path

When designing your checkout customer journey, it's important to consider that the security limitations of the `implicit` token (as used by your storefront) mean you cannot retrieve detailed order information directly from the storefront after checkout. This means that to provide a cohesive order confirmation page, you must retain information from the checkout process and pass it to your order confirmation page or component.

### Retaining Checkout Information

During the checkout process, capture and store the order details before redirecting to the confirmation page.

First, if you need to retrieve your **cart** data (since carts are persisted in Elastic Path), here's how you do it:

```javascript
import { getACart, getCartId } from "@epcc-sdk/sdks-shopper";

// Retrieve current cart data with items
async function getCurrentCartData() {
  const cartId = getCartId();
  if (!cartId) {
    throw new Error("No cart found. Please add items to your cart first.");
  }

  const cartResponse = await getACart({
    path: {
      cartID: cartId,
    },
    query: {
      include: "items",
    },
  });

  const cartData = cartResponse.data;
  if (!cartData?.data || cartData.data.length === 0) {
    throw new Error("Cart is empty. Please add items before checkout.");
  }

  return cartData;
}
```

### Constructing Order Data

The `orderData` object should contain all the information needed to display the order confirmation. You need to build this during the checkout process by combining data from multiple sources:

```javascript
// Example: Building orderData during checkout
async function buildOrderData(customerData, cartData, paymentResponse) {
  const orderData = {
    // Order identifiers - from payment response
    id: paymentResponse.data?.data?.order?.id,
    reference: paymentResponse.data?.data?.order?.reference,
    status: paymentResponse.data?.data?.order?.status,
    completed_at: new Date().toISOString(),

    // Financial information - from payment response
    total:
      paymentResponse.data?.data?.order?.meta?.display_price?.with_tax
        ?.formatted,
    subtotal:
      paymentResponse.data?.data?.order?.meta?.display_price?.without_tax
        ?.formatted,
    tax: paymentResponse.data?.data?.order?.meta?.display_price?.tax?.formatted,

    // Items purchased - from original cart data
    items: cartData.data, // Cart items with their pricing and details

    // Customer information - from checkout form data
    customer: {
      name: customerData.customer?.name,
      email: customerData.customer?.email,
    },

    // Address information - from checkout form data
    billing_address: customerData.billing_address,
    shipping_address: customerData.shipping_address,
  };

  return orderData;
}

// Usage during checkout:
const cartData = await getCurrentCartData(); // Get cart items
const paymentResponse = await paymentSetup({
  /* ... */
}); // Complete payment
const orderData = buildOrderData(customerData, cartData, paymentResponse);
```

**Data Sources Breakdown:**

| Type             | Source                               |
| ---------------- | ------------------------------------ |
| Order details    | `paymentSetup()` response            |
| Financial totals | `paymentSetup()` response            |
| Items purchased  | Cart data via `getCurrentCartData()` |
| Customer info    | Checkout form input                  |
| Addresses        | Checkout form input                  |

## Order Confirmation Best Practices

Creating an effective order confirmation page is crucial for customer satisfaction and retention:

### Key Elements to Include

1. **Order summary** - List of purchased items, quantities, and prices
2. **Order ID / reference number** - For customer support queries
3. **Shipping information** - Delivery address and estimated arrival
4. **Payment details** - Payment method used, billing address
5. **Next steps guidance** - Order tracking information and "Continue shopping" option

## Next Steps

- [Cart Cleanup](./cleanup-carts)
- [Customer Checkout](./customer-checkout)
- [Guest Checkout](./guest-checkout)

---

## Shipping Groups for Split Shipping


This guide explains how to implement [shipping groups](https://elasticpath.dev/docs/ship-groups/shipping-groups/index) in your Elastic Path storefront for complex shipping scenarios. Shipping groups provide a structured approach when you need to split orders into multiple shipments with different addresses, delivery methods, or pricing.

### Creating Shipping Groups

```javascript
async function createShippingGroup(cartId, shippingData) {
  try {
    const response = await fetch(
      `https://euwest.api.elasticpath.com/v2/carts/${cartId}/shipping-groups`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          data: {
            type: "shipping_group",
            name: shippingData.name,
            description: shippingData.description,
            shipping_address: shippingData.shipping_address,
            delivery_instructions: shippingData.delivery_instructions,
            // Shipping pricing
            shipping_price: {
              amount: shippingData.price_amount,
              currency: "USD",
            },
          },
        }),
      },
    );

    const shippingGroup = await response.json();
    return shippingGroup.data;
  } catch (error) {
    console.error("Failed to create shipping group:", error);
    throw error;
  }
}
```

### Retrieving Shipping Groups

```javascript
async function getCartShippingGroups(cartId) {
  try {
    const response = await fetch(
      `https://euwest.api.elasticpath.com/v2/carts/${cartId}/shipping-groups`,
      {
        method: "GET",
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "Content-Type": "application/json",
        },
      },
    );

    const shippingGroups = await response.json();
    return shippingGroups.data;
  } catch (error) {
    console.error("Failed to retrieve shipping groups:", error);
    throw error;
  }
}
```

### Updating Shipping Groups

```javascript
async function updateShippingGroup(cartId, shippingGroupId, updateData) {
  try {
    const response = await fetch(
      `https://euwest.api.elasticpath.com/v2/carts/${cartId}/shipping-groups/${shippingGroupId}`,
      {
        method: "PUT",
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          data: {
            type: "shipping_group",
            ...updateData,
          },
        }),
      },
    );

    const updatedGroup = await response.json();
    return updatedGroup.data;
  } catch (error) {
    console.error("Failed to update shipping group:", error);
    throw error;
  }
}
```

## Split Shipping Example

Here's a complete example for handling split shipping to multiple addresses:

```javascript
async function setupSplitShipping(cartId, cartItems) {
  try {
    // Group 1: Electronics to home address
    const electronicsGroup = await createShippingGroup(cartId, {
      name: "Electronics Shipment",
      description: "Gaming console and accessories",
      shipping_address: {
        first_name: "John",
        last_name: "Doe",
        line_1: "123 Home St",
        city: "New York",
        region: "NY",
        postcode: "10001",
        country: "US",
      },
      delivery_instructions: "Leave at front door",
      price_amount: 1500, // $15.00 express shipping
    });

    // Group 2: Gifts to office address
    const giftGroup = await createShippingGroup(cartId, {
      name: "Gift Shipment",
      description: "Birthday gifts for colleague",
      shipping_address: {
        first_name: "John",
        last_name: "Doe",
        company_name: "Tech Corp",
        line_1: "456 Office Blvd",
        city: "New York",
        region: "NY",
        postcode: "10002",
        country: "US",
      },
      delivery_instructions: "Deliver to reception",
      price_amount: 500, // $5.00 standard shipping
    });

    // Associate items with shipping groups
    await associateItemsWithShippingGroups(
      cartId,
      cartItems,
      {
        electronics: electronicsGroup.id,
        gifts: giftGroup.id,
      },
      accessToken,
    );

    return {
      electronicsGroup,
      giftGroup,
    };
  } catch (error) {
    console.error("Failed to setup split shipping:", error);
    throw error;
  }
}

async function associateItemsWithShippingGroups(
  cartId,
  cartItems,
  groupMapping,
  accessToken,
) {
  for (const item of cartItems) {
    // Determine which shipping group this item belongs to
    const groupKey = item.group; // e.g., 'electronics', 'gifts', etc.
    const shippingGroupId = groupMapping[groupKey];
    if (!shippingGroupId) continue; // Skip if no group mapping

    try {
      const response = await fetch(
        `https://euwest.api.elasticpath.com/v2/carts/${cartId}/items/${item.id}`,
        {
          method: "PUT",
          headers: {
            Authorization: `Bearer ${accessToken}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            data: {
              type: "cart_item",
              shipping_group_id: shippingGroupId,
            },
          }),
        },
      );
      if (!response.ok) {
        throw new Error(
          `Failed to update item ${item.id}: ${response.statusText}`,
        );
      }
      console.log(
        `Item ${item.id} associated with shipping group ${shippingGroupId}`,
      );
    } catch (error) {
      console.error("Error associating item with shipping group:", error);
    }
  }
}
```

## Combining Custom Items and Shipping Groups

You can use both approaches together for maximum flexibility:

```javascript
import { addCustomItemToCart } from "@epcc-sdk/sdks-shopper";

async function hybridShippingApproach(cartId, shippingRequirements) {
  // Use shipping groups for split deliveries
  if (shippingRequirements.hasMultipleAddresses) {
    await setupSplitShipping(cartId, shippingRequirements.addressGroups);
  }

  // Add custom items for additional fees
  if (shippingRequirements.hasInsurance) {
    await addCustomItemToCart({
      path: { cartID: cartId },
      body: {
        data: {
          type: "custom_item",
          name: "Shipping Insurance",
          sku: "SHIP-INSURANCE",
          description: "Package protection coverage",
          quantity: 1,
          price: { amount: 299 }, // $2.99
        },
      },
    });
  }

  if (shippingRequirements.hasHandlingFee) {
    await addCustomItemToCart({
      path: { cartID: cartId },
      body: {
        data: {
          type: "custom_item",
          name: "Special Handling",
          sku: "SHIP-HANDLING",
          description: "Fragile item handling fee",
          quantity: 1,
          price: { amount: 500 }, // $5.00
        },
      },
    });
  }
}
```

## Next Steps

- [Manage Shipping Options](./manage-shipping) - For simple shipping with custom cart items
- [Order Confirmation](./order-confirmation)
- [Customer Checkout](./customer-checkout)

---

## Overview(Checkout)

# Checkout Process Overview

The checkout process is a critical part of any e-commerce application, transforming a shopper's cart into a confirmed order. This guide explains the concepts, components, and lifecycle of the Elastic Path checkout process.

```mermaid
flowchart TD
    A[Customer adds product to cart] --> B[Cart created]
    B --> C[Manage cart items]
    C --> D[Check out cart]
    D --> E[Order created with 'incomplete' status]
    E --> F[Process payment]
    F --> G[Order status: 'processing']
    G --> H{Payment successful?}
    H -->|Yes| I[Order status: 'complete']
    H -->|No| J[Payment declined]
    J --> F
    I --> K[Fulfillment: 'unfulfilled']
    K --> L[Ship order]
    L --> M[Fulfillment: 'fulfilled']

    style E fill:#FFF2CC,stroke:#D6B656
    style G fill:#FFF2CC,stroke:#D6B656
    style I fill:#D5E8D4,stroke:#82B366
    style J fill:#F8CECC,stroke:#B85450
    style M fill:#D5E8D4,stroke:#82B366
```

## Checkout Workflow

When a shopper initiates the checkout process, an order is created from the cart. The order is incomplete until after a successful payment is made. Typically, a complete order can be shipped and the product deducted from inventory counts.

### Summary of the Checkout Workflow

1. A shopper adds a product to a cart - a cart with an ID is created automatically.
2. Manage the cart items. For example, a shopper might add items, remove items, and change quantities.
3. Check out the cart. An incomplete order is created.
4. Pay for an order: by providing billing and shipping details, the order is now in the processing status.
5. If using a manual gateway, after you authorize and capture it, Elastic Path considers the order complete. If you use a third-party integration supported by Elastic Path (such as Stripe), after the third-party gateway authorizes and captures the payment, the order becomes complete.
6. After the order is shipped, you can manually flag it as fulfilled.

## Cart to Order Conversion

When converting a cart to an order through the checkout process, it's important to understand:

- The cart **remains intact** during checkout and is still available afterward
- The cart can be modified and checked out again if needed
- A new, incomplete order is created from the cart contents: i.e. an order is a 'snapshot' of a cart
- The order initially has an "incomplete" status until payment is processed
- If shipping groups are associated with the cart, they're transferred to the order during checkout

## Order Lifecycle

After checkout, the order moves through several states:

1. **Incomplete**: Initial state after checkout, before payment
2. **Processing**: After payment is initiated but not fully complete
3. **Complete**: After successful payment processing
4. **Fulfilled/Unfulfilled**: Shipping status, managed separately from the order status

The checkout process only creates the order in the "incomplete" state. Payment processing is required to advance the order to "complete" status.

## Cart and Inventory Considerations

### Cart Persistence

By default, carts are automatically deleted 7 days after the last update. This can be modified in your store settings.

### Inventory Management

If inventory tracking is enabled, product stock levels are adjusted during the checkout and payment process.

### Currency Requirements

All items in the cart must share the same currency. The cart currency is set when the first item is added.

## Checkout Methods

In Elastic Path there are two types of checkout:

### Guest Checkout

For new customers or those who prefer to shop as guests, you can checkout using a customer object with name and email. This is ideal for first-time visitors or customers who don't want to create an account.

:::tip

#### Why implement guest checkout?

Guest checkout allows shoppers to complete a purchase without creating an account or logging in. This approach can be beneficial for both shoppers and merchants, since it reduces friction in the checkout process. Requiring users to register or log in can be a barrier to completing a purchase, especially for new or infrequent shoppers.
:::

### Customer Checkout

For returning or known shoppers, you can use the Customer Checkout method. This approach requires the shopper to have an existing account and to authenticate (log in) before proceeding with checkout.

:::tip

#### Why implement customer checkout?

Customer checkout enables you to offer a more personalized shopping experience. With customer accounts, you can provide order history, saved addresses, targeted promotions, and more.
:::

You may choose to implement one or both checkout methods, depending on your specific needs.

#### Understanding Customer Checkout Options

Elastic Path Commerce provides two main approaches for authenticated customer checkout:

##### Account Checkout

Can be used for D2C storefronts, but is ideal for B2B scenarios with organizational structures. Benefits include:

- Account and Account Member relationship management
- Account-specific pricing and catalogs
- Account-level billing and purchasing controls

##### Customer ID Checkout

Best for B2C scenarios where you have individual customer records.

:::note
Customer ID checkout relies on the Customers service. [Accounts](/docs/api/accounts/account-management-introduction#accounts-vs-customers) represent the next generation of the Customers service. We recommend using Accounts for new implementations.
:::

- Uses an existing customer ID from your store
- Streamlines checkout for returning customers
- Associates orders with customer records for history tracking

## Shipping Options

Elastic Path provides flexible approaches for managing shipping during checkout, allowing you to implement everything from simple flat-rate shipping to complex split-delivery scenarios:

### Custom Cart Items for Shipping

The most common approach uses [custom cart items](./how-to/manage-shipping) to add shipping fees and delivery options directly to the cart. Custom cart items integrate relatively seamlessly with the existing cart and checkout flow.

### Shipping Groups for Complex Scenarios

For advanced split-shipping requirements, [shipping groups](./how-to/shipping-groups) provide structured support for more complex use cases. Shipping groups are transferred from cart to order during checkout, maintaining the split-shipping configuration throughout the order lifecycle.

#### When to Use Shipping Groups vs Custom Cart Items

Below is a guide to common shipping scenarios and the recommended approach:

| **Scenario**                                         | **Custom Cart Items** | **Shipping Groups** |
| ---------------------------------------------------- | :-------------------: | :-----------------: |
| Single shipping fee for entire cart                  |          ✅           |         ❌          |
| Simple shipping options (standard/express/overnight) |          ✅           |         ❌          |
| Dynamic costs (location, weight, or cart-based)      |          ✅           |         ❌          |
| Additional services (insurance, handling fees)       |          ✅           |         ❌          |
| Multiple delivery addresses                          |          ❌           |         ✅          |
| Split shipping with individual tracking              |          ❌           |         ✅          |
| Bundle items that ship together                      |          ❌           |         ✅          |
| Third-party shipping API integration                 |          ✅           |         ✅          |

## Optional Fields

The Checkout API allows you to include optional fields:

- **order_number**: A user-managed field that can be used as an alternative to the system-generated `order_id`. When processing transactions through certain payment gateways like Authorize.net, the `order_number` may be used in the invoice section.
- **external_ref**: An optional external reference for integrating with other systems.

## Best Practices

### Address Validation

Consider implementing address validation to ensure shipping addresses are correct, reducing failed deliveries and improving customer satisfaction.

### Error Handling

Implement robust error handling during checkout to provide clear feedback to customers when issues occur.

### Progress Indicators

Use clear progress indicators to show customers where they are in the checkout process and how many steps remain.

### Persistent Cart

Implement cart persistence for returning customers, allowing them to continue shopping where they left off.

## Next Steps

Now that you understand the checkout process, you can:

- Implement a [basic checkout flow](./quickstart) with our quickstart guide
- Understand [payment gateway](./payments/overview) integration options

:::tip
For a complete example, check out the [SPA Checkout Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-checkout) in the Elastic Path Composable Frontend repository.
:::

---

## Implement Card Payments


This guide explains how to implement card payments using Elastic Path Payments powered by Stripe and the Elastic Path Shopper SDK. We'll cover both recommended implementation approaches:

1. **Using Stripe Payment Element** - The recommended approach providing a complete, customizable UI component
2. **Using Direct Tokenization** - An alternative approach for more custom implementations

## Prerequisites

- Elastic Path Payments enabled in your store
- API client credentials with appropriate permissions
- A cart that has been converted to an order
- `@epcc-sdk/sdks-shopper` package installed in your project

## Understanding the Payment Flow

Processing card payments with Elastic Path Payments follows a specific sequence of steps. Based on real implementations, the complete flow is:

1. **Add shipping costs**: Add shipping as a custom item to the cart (if applicable)
2. **Submit payment form**: Call `elements?.submit()` to validate the Stripe form
3. **Convert cart to order**: Create an order from the shopper's cart (guest or account checkout)
4. **Initiate payment**: Start payment against the order with Elastic Path Payments
5. **Confirm with Stripe**: Use `stripe.confirmPayment()` with the client secret and payment elements
6. **Confirm with Elastic Path**: Complete the payment confirmation with the order confirmation endpoint

This flow ensures proper validation, 3D Secure handling, and payment confirmation across both Stripe and Elastic Path systems.

## Adding Shipping Costs

Before converting a cart to an order, you may need to add shipping costs as a custom item:

```javascript
import { addCustomItemToCart } from "@epcc-sdk/sdks-shopper";

async function addShippingToCart(cartId, shippingMethod, shippingAmount) {
  return await addCustomItemToCart({
    path: {
      cartID: cartId,
    },
    body: {
      data: {
        type: "custom_item",
        name: "Shipping",
        sku: shippingMethod,
        quantity: 1,
        price: {
          amount: shippingAmount,
          includes_tax: true,
        },
      },
    },
  });
}
```

## Converting Cart to Order

You'll need to convert the cart to an order before processing payment. This can be done for both guest and account checkouts:

```javascript
import { checkoutApi, checkoutWithAccountApi } from "@epcc-sdk/sdks-shopper";

// For guest checkout
async function checkoutAsGuest(cartId, customerData) {
  return await checkoutApi({
    path: {
      cartID: cartId,
    },
    body: {
      data: {
        customer: {
          email: customerData.email,
          name: customerData.name,
        },
        billing_address: customerData.billingAddress,
        shipping_address: customerData.shippingAddress,
      },
    },
  });
}

// For account checkout
async function checkoutWithAccount(cartId, accountData, accountToken) {
  return await checkoutWithAccountApi({
    path: {
      cartID: cartId,
    },
    body: {
      data: {
        contact: {
          name: accountData.name,
          email: accountData.email,
        },
        token: accountToken,
        billing_address: accountData.billingAddress,
        shipping_address: accountData.shippingAddress,
      },
    },
  });
}
```

## Using Stripe Payment Element (Recommended)

Stripe Payment Element is a pre-built, customizable UI component that handles collecting and validating payment details securely.

### Install Dependencies

```bash
npm install @stripe/stripe-js
```

### Complete Implementation Example

Here's a complete example showing the integration of cart checkout and payment processing using the Payment Element approach:

```jsx
import {
  addCustomItemToCart,
  checkoutApi,
  paymentSetup,
  confirmPayment,
} from "@epcc-sdk/sdks-shopper";
import { loadStripe } from "@stripe/stripe-js";
import type { CheckoutForm } from "./types";

export type PaymentCompleteProps = {
  cartId: string;
};

export type PaymentCompleteReq = {
  data: CheckoutForm;
};

export async function completePayment(
  { cartId }: PaymentCompleteProps,
  data: CheckoutForm,
  stripe: any,
  elements: any,
) {
  const { shippingAddress, billingAddress, sameAsShipping, shippingMethod } =
    data;

  const customerName = `${shippingAddress.first_name} ${shippingAddress.last_name}`;

  const checkoutProps = {
    billing_address:
      billingAddress && !sameAsShipping ? billingAddress : shippingAddress,
    shipping_address: shippingAddress,
  };

  /**
   * The handling of shipping options is not production ready.
   * You must implement your own based on your business needs.
   */
  const shippingAmount =
    staticDeliveryMethods.find((method) => method.value === shippingMethod)
      ?.amount ?? 0;

  /**
   * Using a cart custom_item to represent shipping for demo purposes.
   */
  const cartInclShipping = await addCustomItemToCart({
    path: {
      cartID: cartId,
    },
    body: {
      data: {
        type: "custom_item",
        name: "Shipping",
        sku: shippingMethod,
        quantity: 1,
        price: {
          amount: shippingAmount,
          includes_tax: true,
        },
      },
    },
  });

  await elements?.submit();

  /**
   * 1. Convert our cart to an order we can pay
   */
  const createdOrder = await checkoutApi({
    path: {
      cartID: cartId,
    },
    body: {
      data: {
        customer: {
          email: data.guest.email,
          name: customerName,
        },
        ...checkoutProps,
      },
    },
  });

  /**
   * 2. Start payment against the order
   */
  const confirmedPayment = await paymentSetup({
    path: {
      orderID: createdOrder.data.id,
    },
    body: {
      data: {
        gateway: "elastic_path_payments_stripe",
        method: "purchase",
        payment_method_types: ["card"],
      },
    },
  });

  /**
   * 3. Confirm the payment with Stripe
   */
  const stripeConfirmResponse = await stripe?.confirmPayment({
    elements: elements!,
    clientSecret: confirmedPayment.data.payment_intent.client_secret,
    redirect: "if_required",
    confirmParams: {
      return_url: `${window.location.href}/thank-you`,
      payment_method_data: {
        billing_details: {
          address: {
            country: billingAddress?.country,
            postal_code: billingAddress?.postcode,
            state: billingAddress?.region,
            city: billingAddress?.city,
            line1: billingAddress?.line_1,
            line2: billingAddress?.line_2,
          },
        },
      },
    },
  });

  if (stripeConfirmResponse?.error) {
    throw new Error(stripeConfirmResponse.error.message);
  }

  /**
   * 4. Confirm the payment with Elastic Path
   */
  const resultingConfirmation = await confirmPayment({
    path: {
      orderID: createdOrder.data.id,
      transactionID: confirmedPayment.data.id,
    },
    body: {
      data: {
        options: {},
      },
    },
  });

  return {
    order: createdOrder,
    payment: confirmedPayment,
    cart: cartInclShipping,
  };
}
```

## Testing Your Implementation

When testing payments, use these Stripe test cards:

| Card Number         | Scenario                          |
| ------------------- | --------------------------------- |
| 4242 4242 4242 4242 | Successful payment                |
| 4000 0000 0000 3220 | 3D Secure authentication required |
| 4000 0000 0000 9995 | Payment declined                  |

Use any future expiration date, any three-digit CVC, and any postal code.

## Error Handling

Implement robust error handling to provide a good user experience:

```javascript
try {
  // Process payment
} catch (error) {
  if (error.response?.data?.errors) {
    const errorData = error.response.data.errors[0];

    if (errorData.status === "402") {
      // Payment declined
      showError("Your card was declined. Please try another card.");
    } else if (errorData.status === "400") {
      // Validation error
      showError("Invalid payment information: " + errorData.detail);
    } else {
      // Other API error
      showError("An error occurred: " + errorData.detail);
    }
  } else if (error.message.includes("network")) {
    // Network error
    showError("Network error. Please check your connection and try again.");
  } else {
    // Generic error
    showError("An error occurred. Please try again.");
  }
}
```

## Security Considerations

When implementing card payments, follow these security best practices:

- Never store actual card details in your application
- Always use HTTPS for all payment-related communications
- Implement proper validation for all user inputs
- Use Content Security Policy (CSP) to prevent XSS attacks
- Keep your Stripe.js and SDK packages updated

---

## Understanding Elastic Path Payments


This document provides an overview of Elastic Path Payments powered by Stripe and its supported features.

## What is Elastic Path Payments?

Elastic Path Payments, powered by Stripe, is a payment gateway that integrates with your Elastic Path Commerce store to provide a complete payment processing solution.

The gateway interacts directly with Stripe to handle payment processing, authorization, and settlement, providing a seamless checkout experience for your customers while simplifying payment management for your business.

## Features and Capabilities

Elastic Path Payments offers a comprehensive set of features:

- **Multiple Payment Methods**: Support for credit/debit cards, digital wallets, and local payment methods
- **Global Currency Support**: Process payments in multiple currencies
- **Fraud Prevention**: Built-in fraud detection and prevention tools
- **Subscription Management**: Support for recurring billing and subscription payments
- **PCI Compliance**: Reduced PCI compliance burden through tokenization
- **Payment Optimization**: Smart routing and recovery tools to maximize payment success rates
- **Pre-built UI Components**: Ready-to-use UI components for faster implementation

## Integration Benefits

Integrating Elastic Path Payments provides several advantages:

- **Simplified Implementation**: Pre-built components and SDKs reduce development time
- **Unified Commerce Experience**: Seamless integration with your Elastic Path Commerce store
- **Reduced Compliance Burden**: Less PCI compliance work through tokenization
- **Streamlined Operations**: Single platform for payment processing, reporting, and management
- **Improved Conversion Rates**: Optimized checkout flows and support for preferred payment methods
- **Global Reach**: Support for international payment methods and currencies
- **Automatic Updates**: Ongoing updates and improvements without additional development work

## Getting Started

To use Elastic Path Payments, you need to:

1. Reach out to your Customer Success Manager or Customer Success Team to enable the gateway
2. Create a Stripe account through the Stripe Dashboard
3. Complete the onboarding form to set up payments using the gateway
4. Configure the payment gateway in your Commerce Manager

## Next Steps

- [Pay Using Stripe Payment Element](./implement-payments)

---

## Payments Overview


Elastic Path offers a flexible payment system that integrates with various payment gateways to process transactions securely for your commerce application.

## How Payments Work

Payments in Elastic Path follow a simple flow:

1. When a shopper checks out a cart, an unpaid order is created
2. A payment transaction is initiated through a payment gateway
3. The gateway processes the payment outside Elastic Path's environment
4. The transaction status is returned and updates the order status

For security, all payment processing happens externally through payment gateways, using tokens rather than direct card details whenever possible.

## Payment Gateways

Payment gateways are third-party services that process payments for your store. Elastic Path offers:

### Pre-integrated Gateways

- **Elastic Path Payments Powered by Stripe** - Managed payment solution built on Stripe
- **Stripe Payment Intents** - Enhanced Stripe integration with 3D Secure support
- **Adyen** - Global payment platform supporting 250+ payment methods worldwide
- **PayPal Express Checkout** - Digital wallet and payment service from PayPal
- **Braintree** - PayPal-owned payment gateway supporting cards and digital wallets
- **Authorize.Net** - Payment gateway for credit card processing
- **CyberSource** - Visa-owned payment management platform
- **CardConnect** - Payment processing platform with tokenization capabilities

### Special Purpose Gateways

- **Manual Gateway** - For zero-value orders, offline payments, or custom payment methods

Using the manual gateway you could also create custom gateway integrations for payment providers not listed above.

## Payment Methods and Capabilities

Elastic Path supports:

- Standard credit/debit card payments
- Split payments (multiple payment sources for one order)
- Authorization and capture flows
- Full and partial refunds
- Transaction cancellation

### Split Payments

Split payments allow shoppers to use multiple payment sources for a single order, such as:

- Gift card + credit card
- Store credit + credit card
- Multiple payment cards

## Order and Payment Status Workflow

As payments progress, both order and payment statuses update:

| Payment Status       | Order Status | Description                                 |
| -------------------- | ------------ | ------------------------------------------- |
| unpaid               | incomplete   | No complete payment transactions            |
| partially_authorized | incomplete   | Partially authorized with remaining balance |
| partially_paid       | incomplete   | Some funds captured, balance remains        |
| authorized           | processing   | Full amount authorized but not captured     |
| paid                 | complete     | Order fully paid and complete               |

## Refund Options

Refunds can be processed in two ways:

- **Mark as Refunded**: Process the refund in your payment gateway first, then mark it in Elastic Path
- **Refund via API/UI**: Initiate refunds directly through Elastic Path for supported gateways

## Security Considerations

- Payment card data is never stored in Elastic Path
- HTTPS is enforced for all payment communications
- PCI compliance is maintained through external processing

## Next Steps

- [Understanding Elastic Path Payments](./elastic-path-payments/understanding)

---

## Quick Start(Checkout)

# Checkout Quick Start

This guide walks you through the essential steps to implement a basic checkout flow using a manual payment gateway and the customer object method. This is the simplest and easiest to implement form of checkout available in Elastic Path, so it's ideal to help you understand the basic concepts.

You'll learn how to:

- Convert a cart to an order using the customer object method
- Process payment with a manual gateway
- Display order confirmation

For other checkout methods or payment options, refer to our dedicated guides linked at the bottom of this page.

## Prerequisites

- A JavaScript application with Elastic Path SDK installed
- `@epcc-sdk/sdks-shopper` package configured with your client credentials
- A cart with items (see the [Cart Management Quick Start](../cart/quickstart))

```bash
npm install @epcc-sdk/sdks-shopper
```

## Step 1: Collect Customer Information

For this quickstart, we'll checkout a cart using a **customer object**. A customer object contains the shopper's basic information needed for checkout, such as name, email, and address. This might commonly be thought of as a 'guest checkout'. It's the most flexible checkout method and doesn't require authentication tokens or stored customer IDs.

```typescript
import { getCartId } from "@epcc-sdk/sdks-shopper";

// Collect customer information from a form
const collectCustomerInfo = (formData) => {
  // Create a structured customer object for checkout
  return {
    customer: {
      email: formData.email,
      name: `${formData.firstName} ${formData.lastName}`,
    },
    billing_address: {
      first_name: formData.billingFirstName || formData.firstName,
      last_name: formData.billingLastName || formData.lastName,
      company_name: formData.billingCompany || "",
      line_1: formData.billingLine1,
      line_2: formData.billingLine2 || "",
      city: formData.billingCity,
      county: formData.billingCounty || "",
      region: formData.billingRegion || "",
      postcode: formData.billingPostcode,
      country: formData.billingCountry,
    },
    shipping_address: {
      first_name: formData.shippingFirstName || formData.firstName,
      last_name: formData.shippingLastName || formData.lastName,
      company_name: formData.shippingCompany || "",
      phone_number: formData.shippingPhone || "",
      line_1: formData.shippingLine1,
      line_2: formData.shippingLine2 || "",
      city: formData.shippingCity,
      county: formData.shippingCounty || "",
      region: formData.shippingRegion || "",
      postcode: formData.shippingPostcode,
      country: formData.shippingCountry,
      instructions: formData.shippingInstructions || "",
    },
  };
};
```

## Step 2: Convert Cart to Order

When a cart is ready for checkout, convert it to an order through the checkout process:

```typescript
import { checkoutApi, getCartId } from "@epcc-sdk/sdks-shopper";

// Checkout the cart to create an order
const checkoutCart = async (customerData) => {
  const cartId = getCartId();

  if (!cartId) {
    throw new Error("No cart found");
  }

  try {
    const response = await checkoutApi({
      path: {
        cartID: cartId,
      },
      body: {
        data: customerData,
      },
    });

    return response.data;
  } catch (error) {
    console.error("Checkout failed:", error);
    throw error;
  }
};
```

## Step 3: Process Payment with Manual Gateway

For this quickstart, we'll use a manual payment gateway:

```typescript
import { paymentSetup } from "@epcc-sdk/sdks-shopper";

// Process payment using a manual gateway
const processPayment = async (orderId) => {
  try {
    const response = await paymentSetup({
      path: {
        orderID: orderId,
      },
      body: {
        data: {
          gateway: "manual",
          method: "purchase",
        },
      },
    });

    return response.data;
  } catch (error) {
    console.error("Payment processing failed:", error);
    throw error;
  }
};
```

## Step 4: Order Confirmation

Display order confirmation to the customer and clear the cart:

```typescript
// Handle order completion
const completeOrder = (orderData) => {
  // Clear cart ID and other checkout related data
  localStorage.removeItem("ep_cart_id");

  // Return order information for confirmation page
  return {
    orderId: orderData.id,
    orderReference: orderData.reference,
    orderStatus: orderData.status,
    orderTotal: orderData.meta?.display_price?.with_tax?.formatted,
  };
};
```

## Complete Example

Here's how to put it all together in a simple React component:

```jsx
import React, { useState } from "react";
import { getCartId, checkoutApi, paymentSetup } from "@epcc-sdk/sdks-shopper";

function SimpleCheckout() {
  const [formData, setFormData] = useState({
    email: "",
    firstName: "",
    lastName: "",
    billingLine1: "",
    billingCity: "",
    billingPostcode: "",
    billingCountry: "",
    // Add more fields as needed
  });
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  const [orderConfirmation, setOrderConfirmation] = useState(null);

  const handleInputChange = (e) => {
    const { name, value } = e.target;
    setFormData((prev) => ({ ...prev, [name]: value }));
  };

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    setError(null);

    try {
      // Step 1: Prepare customer data
      const customerData = {
        customer: {
          email: formData.email,
          name: `${formData.firstName} ${formData.lastName}`,
        },
        billing_address: {
          first_name: formData.firstName,
          last_name: formData.lastName,
          line_1: formData.billingLine1,
          city: formData.billingCity,
          postcode: formData.billingPostcode,
          country: formData.billingCountry,
        },
        shipping_address: {
          first_name: formData.firstName,
          last_name: formData.lastName,
          line_1: formData.billingLine1,
          city: formData.billingCity,
          postcode: formData.billingPostcode,
          country: formData.billingCountry,
        },
      };

      // Step 2: Checkout the cart
      const cartId = getCartId();
      const checkoutResponse = await checkoutApi({
        path: {
          cartID: cartId,
        },
        body: {
          data: customerData,
        },
      });

      const orderId = checkoutResponse.data?.data?.id;

      // Step 3: Process payment
      const paymentResponse = await paymentSetup({
        path: {
          orderID: orderId,
        },
        body: {
          data: {
            gateway: "manual",
            method: "purchase",
          },
        },
      });

      // Step 4: Order confirmation
      const orderData = paymentResponse.data?.data;

      // Clear cart and set confirmation
      localStorage.removeItem("ep_cart_id");
      setOrderConfirmation({
        orderId: orderData.order.id,
        orderReference: orderData.order.reference,
        orderStatus: orderData.order.status,
      });
    } catch (err) {
      setError("Checkout failed. Please try again.");
      console.error(err);
    } finally {
      setLoading(false);
    }
  };

  if (orderConfirmation) {
    return (
      
        Order Confirmed!
        Order ID: {orderConfirmation.orderId}
        Reference: {orderConfirmation.orderReference}
        Status: {orderConfirmation.orderStatus}
      
    );
  }

  return (
    <form onSubmit={handleSubmit}>
      Checkout
      {error && {error}}

      
        <label htmlFor="email">Email</label>
        <input
          type="email"
          id="email"
          name="email"
          value={formData.email}
          onChange={handleInputChange}
          required
        />
      

      
        <label htmlFor="firstName">First Name</label>
        <input
          type="text"
          id="firstName"
          name="firstName"
          value={formData.firstName}
          onChange={handleInputChange}
          required
        />
      

      {/* Add more form fields for lastName, billing address, etc. */}

      <button type="submit" disabled={loading}>
        {loading ? "Processing..." : "Complete Checkout"}
      </button>
    </form>
  );
}
```

## Next Steps

Now that you've implemented a basic checkout flow, explore these advanced topics:

- [Full guest checkout guide](./how-to/guest-checkout) - View a complete guest checkout example
- [Checkout a customer](./how-to/customer-checkout) - Checkout a known customer
- [Order Confirmation](./how-to/order-confirmation) - Order confirmation best practices
- [Cart Cleanup](./how-to/cleanup-carts) - How to clean up carts after checkout

:::tip
For a complete example, check out the [SPA Checkout Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-checkout) in the Elastic Path Composable Frontend repository.
:::

---

## Add Bundle to Cart

Learn how to add bundles to cart, handle configuration for dynamic bundles, and manage common errors.

## Goal

Successfully add both fixed and dynamic bundles to cart with proper validation and user feedback.

## Prerequisites

- Bundle product data with components
- Active cart session
- User selections for dynamic bundles

## Quick Start

```typescript
import { 
  client, 
  configureByContextProduct, 
  manageCarts, 
  getCartId,
  getAllFiles 
} from '@epcc-sdk/sdks-shopper';

// Configure client
client.setConfig({
  baseUrl: 'https://euwest.api.elasticpath.com',
  headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
});

// Add bundle to cart (automatically detects type)
async function addBundleToCart(
  bundle: BundleProduct,
  selectedOptions?: BundleConfiguration["selected_options"],
  quantity: number = 1
) {
  const cartId = getCartId();
  
  // Detect if bundle is dynamic based on min/max requirements
  const isDynamic = bundle.attributes?.components && 
    Object.values(bundle.attributes.components).some(
      comp => comp.min != null || comp.max != null
    );
  
  if (isDynamic && selectedOptions) {
    // Dynamic bundles with user selections need configuration
    const config = await configureByContextProduct({
      path: { product_id: bundle.id },
      body: { data: { selected_options: selectedOptions } }
    });
    
    // Add with configuration
    return await manageCarts({
      path: { cartID: cartId },
      body: { 
        data: { 
          type: 'cart_item',
          id: bundle.id,
          quantity,
          bundle_configuration: config.data?.meta?.bundle_configuration
        }
      }
    });
  } else {
    // Fixed bundles or dynamic bundles without selections
    // API will use default configuration automatically
    return await manageCarts({
      path: { cartID: cartId },
      body: { 
        data: { 
          type: 'cart_item',
          id: bundle.id,
          quantity
        }
      }
    });
  }
}
```

:::tip Bundle Configuration
- **Dynamic bundles with user selections**: Require `bundle_configuration` property
- **Fixed bundles**: Can be added without configuration - the API uses default configuration automatically
- **Dynamic bundles without selections**: Will use minimum required selections as defaults
:::

## Key Concepts

### Validate Bundle Configuration

Ensure dynamic bundle selections meet component requirements:

```typescript
interface ValidationResult {
  isValid: boolean;
  errors: string[];
  warnings: string[];
}

function validateBundleConfiguration(
  components: Components,
  selectedOptions: BundleConfiguration["selected_options"]
): ValidationResult {
  const errors: string[] = [];
  const warnings: string[] = [];
  
  // Check each component's requirements
  Object.entries(components).forEach(([componentKey, component]) => {
    const selected = selectedOptions[componentKey] || {};
    const selectedCount = Object.values(selected)
      .reduce((sum, qty) => sum + Number(qty), 0);
    
    // Validate minimum requirement
    if (component.min && selectedCount < component.min) {
      errors.push(
        `${component.name}: Please select at least ${component.min} option(s)`
      );
    }
    
    // Validate maximum requirement
    if (component.max && selectedCount > component.max) {
      errors.push(
        `${component.name}: Maximum ${component.max} option(s) allowed`
      );
    }
    
    // Warn about optional components
    if (!component.min && selectedCount === 0) {
      warnings.push(
        `${component.name}: No selection made (optional)`
      );
    }
  });
  
  return {
    isValid: errors.length === 0,
    errors,
    warnings
  };
}
```

### Auto-Replacement for Maximum Selections

Provide better UX by automatically replacing the oldest selection when maximum is reached:

```typescript
function handleComponentSelection(
  componentKey: string,
  optionId: string,
  component: ComponentProduct,
  currentSelections: BundleConfiguration["selected_options"]
): BundleConfiguration["selected_options"] {
  const componentSelections = currentSelections[componentKey] || {};
  const selectedCount = Object.keys(componentSelections).length;
  
  if (component.max && selectedCount >= component.max) {
    // Auto-replace oldest selection
    const updated = { ...componentSelections };
    const oldestKey = Object.keys(updated)[0];
    delete updated[oldestKey];
    updated[optionId] = 1;
    
    return {
      ...currentSelections,
      [componentKey]: updated
    };
  }
  
  // Normal addition
  return {
    ...currentSelections,
    [componentKey]: {
      ...componentSelections,
      [optionId]: 1
    }
  };
}
```

### Fetching Component Product Images

When displaying bundle components with images, use the efficient batch fetching pattern described in [Get Bundle - Component Product Images](./get-bundle#component-product-images).

:::tip Key Points
- Component images are not included in the bundle response
- Use `getAllFiles` with an `in()` filter to fetch all images in one API call
- This approach significantly improves performance for bundles with many components
:::

## Best Practices

- Validate dynamic bundle configurations before adding to cart
- Show loading states during async operations
- Handle errors with user-friendly messages
- Fetch component product images efficiently using batch operations

## Common Issues & Solutions

### "Bundle configuration is required" Error
- **Cause**: Attempting to add a dynamic bundle with custom selections but without configuration
- **Solution**: For dynamic bundles with user selections, call `configureByContextProduct` first and include the `bundle_configuration`. Fixed bundles don't require configuration

### "Invalid bundle configuration" Error
- **Cause**: Configuration doesn't meet component requirements
- **Solution**: Validate configuration before sending to API

### "Insufficient stock" Error
- **Cause**: Bundle or components out of stock
- **Solution**: Check inventory before add to cart, show availability

## Next Steps

- [Cart Management](/docs/developer-tools/fundamentals/cart/overview)
- [Checkout Process](/docs/developer-tools/fundamentals/checkout/overview)
- [Order Confirmation](/docs/developer-tools/fundamentals/checkout/how-to/order-confirmation)

## References

- [Add Items to Cart Guide](/docs/api/carts/manage-carts#add-custom-item-to-cart)
- [Bundle Configuration API](/docs/api/pxm/catalog/configure-by-context-product)
- [Cart Management API](/docs/api/carts/manage-carts)
- [Inventory API](/docs/api/pxm/inventory/inventory)

---

## Understanding Bundle Configuration

Learn how bundle configuration works in Elastic Path, understand the data structures, and implement validation. For a practical implementation guide, see [Configure Dynamic Bundles](./configure-dynamic-bundle).

## Configuration Structure

Bundle configuration defines which component options are selected and their quantities:

```typescript
interface BundleConfiguration {
  selected_options: {
    [componentKey: string]: {
      [optionId: string]: number; // Quantity
    };
  };
}

// Example configuration
const configuration: BundleConfiguration = {
  selected_options: {
    "processor": {
      "prod-i9-uuid": 1
    },
    "graphics_card": {
      "prod-rtx4080-uuid": 1
    },
    "storage": {
      "prod-ssd-2tb-uuid": 2  // quantity of 2
    },
    "accessories": {
      "prod-mouse-uuid": 1,
      "prod-keyboard-uuid": 1
    }
  }
};
```

## Key Concepts

### Component Keys
- Unique identifiers for each bundle component
- Match the keys in `bundle.attributes.components`
- Used as top-level properties in configuration

### Option IDs
- Product IDs that can be selected for each component
- Must match available options in component definition
- Used as keys within component configuration

### Quantities
- Number of each option selected
- Must respect min/max constraints
- Always stored as numbers

## Validation

Validate configuration before API calls:

```typescript
function validateConfiguration(
  components: Components,
  configuration: BundleConfiguration["selected_options"]
): { isValid: boolean; errors: string[] } {
  const errors: string[] = [];
  
  // Check each component's requirements
  Object.entries(components).forEach(([componentKey, component]) => {
    const selectedOptions = configuration[componentKey] || {};
    const totalQuantity = Object.values(selectedOptions)
      .reduce((sum, qty) => sum + Number(qty), 0);
    
    // Validate minimum requirement
    if (component.min && totalQuantity < component.min) {
      errors.push(
        `${component.name}: Select at least ${component.min} option(s)`
      );
    }
    
    // Validate maximum requirement
    if (component.max && totalQuantity > component.max) {
      errors.push(
        `${component.name}: Select at most ${component.max} option(s)`
      );
    }
  });
  
  return {
    isValid: errors.length === 0,
    errors
  };
}
```

## Configuration Persistence

Save configurations to improve user experience:

```typescript
// Save to URL for sharing
function saveConfigurationToUrl(
  bundleId: string, 
  configuration: BundleConfiguration["selected_options"]
) {
  const configString = btoa(JSON.stringify(configuration));
  const params = new URLSearchParams(window.location.search);
  params.set('config', configString);
  
  window.history.replaceState(
    {}, 
    '', 
    `${window.location.pathname}?${params.toString()}`
  );
}

// Restore from URL
function restoreConfigurationFromUrl(): BundleConfiguration["selected_options"] | null {
  const params = new URLSearchParams(window.location.search);
  const configString = params.get('config');
  
  if (!configString) return null;
  
  try {
    return JSON.parse(atob(configString));
  } catch (error) {
    console.warn('Invalid configuration in URL');
    return null;
  }
}

// Save to localStorage
function saveConfigurationToStorage(
  bundleId: string,
  configuration: BundleConfiguration["selected_options"]
) {
  const key = `bundle_config_${bundleId}`;
  localStorage.setItem(key, JSON.stringify({
    configuration,
    timestamp: Date.now()
  }));
}
```

## Using Configuration with SDK

Apply configuration when adding to cart:

```typescript
// Configure bundle and get pricing
const configResponse = await configureByContextProduct({
  path: { product_id: bundleId },
  body: {
    data: {
      selected_options: configuration.selected_options
    }
  }
});

// Add to cart with configuration
await manageCarts({
  path: { cartID: cartId },
  body: {
    data: {
      type: 'cart_item',
      id: bundleId,
      quantity: 1,
      bundle_configuration: configResponse.data?.meta?.bundle_configuration
    }
  }
});
```

## Best Practices

1. **Always validate** configuration before API calls
2. **Handle number types** correctly for quantities
3. **Provide clear error messages** for invalid configurations
4. **Consider persistence** for better user experience
5. **Clean up stale data** from storage periodically

## Common Pitfalls

- Not validating option IDs exist in component definition
- Storing quantities as strings instead of numbers
- Forgetting to check min/max constraints
- Losing configuration on page refresh
- Not handling invalid saved configurations gracefully

## Next Steps

Now that you understand bundle configuration:

- [Configure Dynamic Bundles](./configure-dynamic-bundle) - Build a complete bundle configurator UI
- [Bundle Pricing Strategies](./bundle-pricing-strategies) - Handle dynamic pricing
- [Add Bundle to Cart](./add-bundle-to-cart) - Complete cart operations

## References

- [Configure Bundle API](/docs/api/pxm/catalog/configure-by-context-product)
- [Bundle Configuration Guide](/docs/commerce-manager/product-experience-manager/bundles/overview)
- [Composable Frontend Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)

---

## Bundle Pricing Strategies

Learn how bundle pricing works in Elastic Path, how to fetch updated prices as users configure bundles, and best practices for displaying prices.

## Prerequisites

- Bundle product data from [Get Bundle](./get-bundle)
- Component products for dynamic bundles
- Understanding of bundle configuration structure

## Pricing Models

Elastic Path supports two primary bundle pricing models:

### Explicit Pricing
- Bundle has a predetermined price set in PXM
- Price doesn't change with component selection
- Ideal for value bundles and promotional offers

### Auto/Cumulative Pricing
- Price calculated from selected components
- Changes dynamically with configuration
- Perfect for build-your-own bundles

## Pricing Data Structure

Understanding how bundle pricing is structured in the API response:

### Explicit Pricing
Bundle has a fixed price set in PXM:

```typescript
{
  attributes: {
    price: [{
      amount: 99900,
      currency: "USD",
      includes_tax: false
    }]
  },
  meta: {
    display_price: {
      without_tax: {
        amount: 99900,
        currency: "USD",
        formatted: "$999.00"
      }
    }
  }
}
```

### Auto/Cumulative Pricing
Price calculated from selected components:

```typescript
{
  attributes: {
    // No price array or empty
  },
  meta: {
    display_price: {
      without_tax: {
        amount: 0,  // Updates based on configuration
        currency: "USD",
        formatted: "$0.00"
      }
    }
  }
}
```

## Working with Bundle Pricing

When working with bundles, the pricing is automatically handled by the API. Simply configure the bundle with selected options and the returned product will have the correct pricing, regardless of whether it uses explicit or auto pricing.

```typescript
import { configureByContextProduct } from '@epcc-sdk/sdks-shopper';

async function calculateDynamicPrice(
  bundleId: string,
  selectedOptions: BundleConfiguration["selected_options"]
) {
  try {
    // Configure bundle to get updated product with new pricing
    const response = await configureByContextProduct({
      path: { product_id: bundleId },
      body: {
        data: {
          selected_options: selectedOptions
        }
      }
    });
    
    // API returns full product data with updated pricing
    const configuredProduct = response.data?.data;
    const price = configuredProduct?.meta?.display_price?.without_tax;
    
    return {
      amount: price?.amount,
      formatted: price?.formatted,
      currency: price?.currency,
      // Also return the full product if needed for UI updates
      product: configuredProduct
    };
  } catch (error) {
    console.error('Price calculation failed:', error);
    return null;
  }
}
```

## Price Display Implementation

Use the configured product's price data for display:

```typescript
function displayBundlePrice(configuredProduct: Product) {
  // The API returns pricing in meta.display_price
  const price = configuredProduct?.meta?.display_price?.without_tax;
  
  if (!price?.formatted) {
    return Configure bundle to see price;
  }
  
  return {price.formatted};
}
```

### Handling Price Updates

Show loading states while prices update:

```typescript
function BundleConfigurator({ bundle, componentProducts }) {
  const [isUpdatingPrice, setIsUpdatingPrice] = useState(false);
  const [configuredProduct, setConfiguredProduct] = useState(bundle);
  
  const handleSelectionChange = async (newSelection) => {
    setIsUpdatingPrice(true);
    
    try {
      const result = await calculateDynamicPrice(bundle.id, newSelection);
      if (result?.product) {
        setConfiguredProduct(result.product);
      }
    } finally {
      setIsUpdatingPrice(false);
    }
  };
  
  const currentPrice = configuredProduct?.meta?.display_price?.without_tax?.formatted;
  
  return (
    <>
      Price: {isUpdatingPrice ? "Updating..." : currentPrice}
      {/* Component selection UI */}
    </>
  );
}
```

## Performance Tips

- **Show loading states** during price updates to improve perceived performance
- **Debounce rapid selections** to avoid excessive API calls 
- **Update prices through the API** rather than calculating locally
- **Use the configured product response** which includes all pricing information

## Best Practices

1. **Use API for pricing** - Always use `configureByContextProduct` for accurate pricing
2. **Handle loading states** - Show clear feedback while prices update
3. **Display formatted prices** - Use the `meta.display_price` from the API response
4. **Error handling** - Gracefully handle API failures during configuration
5. **Optimize re-renders** - Use React.memo for price components to avoid unnecessary updates

## Common Issues

- **Price not updating**: Ensure selected options format matches API requirements
- **Wrong currency**: Check price book configuration and currency settings
- **Missing prices**: Verify component products have prices in the correct currency
- **Stale prices**: Clear any cached price data when selections change

## Next Steps

- [Get Bundle](./get-bundle) - Fetch bundle data with pricing
- [Configure Dynamic Bundles](./configure-dynamic-bundle) - Build bundle configuration UI
- [Add Bundle to Cart](./add-bundle-to-cart) - Complete the purchase flow

## References

- [Bundle Pricing Guide](/docs/commerce-manager/product-experience-manager/bundles/bundle-pricing)
- [Configure Bundle API](/docs/api/pxm/catalog/configure-by-context-product)
- [Price Books API](/docs/api/pxm/pricebooks/price-books)

---

## Bundle Selection Patterns

Explore different patterns for implementing bundle component selection, each optimized for different use cases and user experiences. Choose and implement the best pattern for your storefront's needs.

## Quick Start

Choose the right bundle selection pattern for your storefront:

```mermaid
flowchart TD
    A[Start] --> B{Visual products?}
    B -->|Yes| C{Many components?}
    B -->|No| D{Complex requirements?}
    C -->|Yes| E[Pattern 4: Visual Builder]
    C -->|No| F[Pattern 1: Checkbox Grid]
    D -->|Yes| G[Pattern 2: Step-by-Step Wizard]
    D -->|No| H[Pattern 3: Accordion View]
    
    style E fill:#C8E6C9,stroke:#388E3C,color:#000
    style F fill:#C8E6C9,stroke:#388E3C,color:#000
    style G fill:#C8E6C9,stroke:#388E3C,color:#000
    style H fill:#C8E6C9,stroke:#388E3C,color:#000
```

### Pattern Overview

1. **[Checkbox Grid](#pattern-1-checkbox-grid)** - Visual grid with images
2. **[Step-by-Step Wizard](#pattern-2-step-by-step-wizard)** - Guided configuration
3. **[Accordion View](#pattern-3-accordion-view)** - Expandable sections
4. **[Visual Builder](#pattern-4-visual-builder)** - Drag-and-drop interface
5. **[Quick Configure Modal](#pattern-5-quick-configure-modal)** - For product listings

## Choosing the Right Pattern

| Pattern | Best For | Implementation Complexity |
|---------|----------|--------------------------|
| **Checkbox Grid** | Visual products, quick selection | 🟢 Simple |
| **Step-by-Step Wizard** | Complex bundles, first-time users | 🟡 Moderate |
| **Accordion View** | Many components, limited space | 🟢 Simple |
| **Visual Builder** | Customizable products, engagement | 🔴 Complex |
| **Quick Configure Modal** | Product lists, quick add | 🟢 Simple |

## Pattern 1: Checkbox Grid

### Overview

Display all component options in a visual grid with checkboxes. This pattern works best for bundles with visual products where shoppers benefit from seeing all options at once.

### When to Use

- Products with strong visual differentiation
- Limited number of components (2-5)
- Quick decision making is important
- Mobile-first experiences

### Implementation

```typescript
function CheckboxGridPattern({ bundle, componentProducts, componentImages }) {
  const [selectedOptions, setSelectedOptions] = useState({});
  const components = bundle.attributes?.components || {};
  
  return Object.entries(components).map(([componentKey, component]) => {
    const isRequired = component.min && component.min > 0;
    const selectedCount = Object.keys(selectedOptions[componentKey] || {}).length;
    const reachedMax = component.max && selectedCount >= component.max;
    
    return (
      <section key={componentKey}>
        {/* Component header with requirements */}
        {component.name} {isRequired && '*'}
        {getSelectionHint(component)}
        
        {/* Option grid */}
        {component.options.map(option => {
          const product = componentProducts.find(p => p.id === option.id);
          const isSelected = selectedOptions[componentKey]?.[option.id];
          const isDisabled = !isSelected && reachedMax;
          
          return (
            <label key={option.id}>
              <input
                type="checkbox"
                checked={isSelected}
                disabled={isDisabled}
                onChange={(e) => handleOptionToggle(
                  componentKey, option.id, e.target.checked, component
                )}
              />
              
              {/* Product image */}
              {renderProductImage(product, componentImages[option.id])}
              
              {/* Product details */}
              {product?.attributes?.name}
              {product?.meta?.display_price?.without_tax?.formatted}
            </label>
          );
        })}
      </section>
    );
  });
}
```

### Smart Selection Behavior (Auto-Replacement)

When maximum selections are reached, clicking a new option automatically deselects the oldest selection:

```typescript
function handleOptionToggle(componentKey, optionId, checked, component) {
  const currentSelections = selectedOptions[componentKey] || {};
  const selectedCount = Object.keys(currentSelections).length;
  
  if (checked && component.max && selectedCount >= component.max) {
    // Auto-replacement behavior: Remove the first (oldest) selection
    const updatedSelections = { ...currentSelections };
    const oldestKey = Object.keys(updatedSelections)[0];
    delete updatedSelections[oldestKey];
    
    // Add the new selection
    updatedSelections[optionId] = 1;
    
    setSelectedOptions(prev => ({
      ...prev,
      [componentKey]: updatedSelections
    }));
  } else if (checked) {
    // Normal selection
    setSelectedOptions(prev => ({
      ...prev,
      [componentKey]: {
        ...currentSelections,
        [optionId]: 1
      }
    }));
  } else {
    // Deselection
    const updatedSelections = { ...currentSelections };
    delete updatedSelections[optionId];
    setSelectedOptions(prev => ({
      ...prev,
      [componentKey]: updatedSelections
    }));
  }
}
```

This provides an intuitive experience where users don't need to manually deselect items before selecting new ones.

### Mobile Optimization

```typescript
// Use responsive grid columns based on screen size
const gridClasses = 'grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5';

// Ensure touch-friendly sizing
const optionCardClasses = 'min-h-[120px] sm:min-h-[140px] touch-manipulation';
```

## Pattern 2: Step-by-Step Wizard

### Overview

Guide users through bundle configuration one component at a time. This pattern reduces cognitive load and ensures all requirements are met.

### When to Use

- Complex bundles with many components
- First-time or infrequent users
- When order of selection matters
- Need to explain component choices

### Implementation

```typescript
function StepByStepWizard({ bundle, componentProducts }) {
  const [currentStep, setCurrentStep] = useState(0);
  const [selectedOptions, setSelectedOptions] = useState({});
  const [visitedSteps, setVisitedSteps] = useState(new Set([0]));
  
  const components = Object.entries(bundle.attributes?.components || {});
  const totalSteps = components.length;
  
  const isStepValid = (stepIndex: number) => {
    const [componentKey, component] = components[stepIndex];
    const selectedCount = Object.keys(selectedOptions[componentKey] || {}).length;
    return validateComponentSelection(component, selectedCount);
  };
  
  return (
    <>
      {/* Progress indicator */}
      {components.map(([key, component], index) => (
        <button
          key={key}
          onClick={() => handleStepClick(index)}
          disabled={!visitedSteps.has(index) && index !== 0}
        >
          {isStepValid(index) ? '✓' : index + 1}
          {component.name}
        </button>
      ))}
      
      {/* Current step content */}
      <StepContent
        component={components[currentStep][1]}
        componentProducts={componentProducts}
        selectedOptions={selectedOptions[components[currentStep][0]] || {}}
        onSelectionChange={(options) => updateSelection(currentStep, options)}
      />
      
      {/* Navigation buttons */}
      <button onClick={handlePrevious} disabled={currentStep === 0}>
        Previous
      </button>
      Step {currentStep + 1} of {totalSteps}
      <button 
        onClick={currentStep < totalSteps - 1 ? handleNext : handleComplete}
        disabled={!isStepValid(currentStep)}
      >
        {currentStep < totalSteps - 1 ? 'Next' : 'Add to Cart'}
      </button>
    </>
  );
}```

function StepContent({ component, componentProducts, selectedOptions, onSelectionChange }) {
  const availableProducts = getAvailableProducts(component.options, componentProducts);
  
  return (
    <>
      {component.name}
      {component.description && {component.description}}
      
      {availableProducts.map(({ id, product }) => {
        const isSelected = !!selectedOptions[id];
        
        return (
           toggleSelection(id, selectedOptions, onSelectionChange)}>
            <input
              type={component.max === 1 ? 'radio' : 'checkbox'}
              checked={isSelected}
              readOnly
            />
            {product.attributes.name}
            {product.attributes.description}
            {product.meta?.display_price?.without_tax?.formatted}
          
        );
      })}
    </>
  );
}
```

## Pattern 3: Accordion View

### Overview

Display components in collapsible sections to save space while maintaining organization. Perfect for bundles with many components or limited screen space.

### When to Use

- Many components (5+)
- Limited screen real estate
- Mobile-first design
- Progressive disclosure needed

### Implementation

```typescript
function AccordionPattern({ bundle, componentProducts }) {
  const [expandedSections, setExpandedSections] = useState<Set<string>>(new Set());
  const [selectedOptions, setSelectedOptions] = useState({});
  const components = bundle.attributes?.components || {};
  
  return (
    <>
      {Object.entries(components).map(([componentKey, component]) => {
        const isExpanded = expandedSections.has(componentKey);
        const selectedCount = Object.keys(selectedOptions[componentKey] || {}).length;
        const isComplete = isComponentComplete(component, selectedCount);
        
        return (
          
            {/* Accordion header */}
            <button onClick={() => toggleSection(componentKey)}>
              {isComplete ? '✓' : '○'}
              {component.name} {component.min > 0 && '*'}
              {selectedCount > 0 && `(${selectedCount} selected)`}
              {/* Chevron icon for expand/collapse */}
            </button>
            
            {/* Accordion content */}
            {isExpanded && (
              <>
                {getSelectionHint(component)}
                
                {component.options.map(option => {
                  const product = componentProducts.find(p => p.id === option.id);
                  const isSelected = selectedOptions[componentKey]?.[option.id];
                  
                  return (
                    <label key={option.id}>
                      <input
                        type="checkbox"
                        checked={!!isSelected}
                        onChange={(e) => handleOptionToggle(
                          componentKey, option.id, e.target.checked
                        )}
                      />
                      {product?.attributes?.name}
                      SKU: {product?.attributes?.sku}
                      {product?.meta?.display_price?.without_tax?.formatted}
                    </label>
                  );
                })}
              </>
            )}
          
        );
      })}
      
      {/* Configuration summary */}
      <ConfigurationSummary 
        selectedOptions={selectedOptions} 
        components={components}
        componentProducts={componentProducts}
      />
    </>
  );
}
```

## Pattern 4: Visual Builder

### Overview

Interactive drag-and-drop or visual assembly interface for building custom bundles. Best for products where visual representation enhances understanding.

### When to Use

- Highly customizable products
- Visual assembly makes sense (computers, furniture)
- Engagement is important
- Desktop-first experiences

### Implementation

```typescript
import { DndProvider } from 'react-dnd';
import { HTML5Backend } from 'react-dnd-html5-backend';

function VisualBuilder({ bundle, componentProducts }) {
  const [configuration, setConfiguration] = useState({});
  
  return (
    <DndProvider backend={HTML5Backend}>
      {/* Component palette */}
      <ComponentPalette
        components={bundle.attributes?.components || {}}
        componentProducts={componentProducts}
      />
      
      {/* Build area with drag-drop zone */}
      <BuildArea
        configuration={configuration}
        onConfigurationChange={setConfiguration}
        components={bundle.attributes?.components || {}}
      />
      
      {/* Configuration summary */}
      <ConfigurationSummary
        configuration={configuration}
        componentProducts={componentProducts}
      />
    </DndProvider>
  );
}

function DraggableComponent({ component, product }) {
  const [{ isDragging }, drag] = useDrag({
    type: 'component',
    item: { componentKey: component.key, productId: product.id, product },
    collect: (monitor) => ({ isDragging: monitor.isDragging() })
  });
  
  return (
    
      {/* Product image if available */}
      {product.image && renderProductImage(product)}
      
      {/* Product info */}
      {product.attributes.name}
      {product.meta?.display_price?.without_tax?.formatted}
    
  );
}

function BuildArea({ configuration, onConfigurationChange, components }) {
  const [{ isOver }, drop] = useDrop({
    accept: 'component',
    drop: (item: any) => {
      const { componentKey, productId } = item;
      
      // Validate drop against component rules
      if (!canAddComponent(components[componentKey], configuration[componentKey])) {
        showError(`Maximum ${components[componentKey].max} allowed`);
        return;
      }
      
      // Add to configuration
      addToConfiguration(onConfigurationChange, componentKey, productId);
    },
    collect: (monitor) => ({ isOver: monitor.isOver() })
  });
  
  return (
    
      {Object.keys(configuration).length === 0 ? (
        // Empty state
        Drag components here to build your bundle
      ) : (
        // Visual representation of configured bundle
        <BundleVisualization 
          configuration={configuration}
          components={components}
        />
      )}
    
  );
}
```

## Pattern 5: Quick Configure Modal

### Overview

Streamlined configuration modal for product listing pages, allowing quick bundle configuration without leaving the list view.

### When to Use

- Product listing pages
- Quick add to cart functionality
- Simple bundles with few options
- Reducing friction in purchase flow

### Implementation

```typescript
function QuickConfigureModal({ bundle, isOpen, onClose, onAddToCart }) {
  const [selectedOptions, setSelectedOptions] = useState({});
  const [isLoading, setIsLoading] = useState(false);
  
  const handleQuickAdd = async () => {
    setIsLoading(true);
    try {
      const configuration = await configureBundle(bundle.id, selectedOptions);
      await onAddToCart(bundle.id, configuration);
      onClose();
    } catch (error) {
      console.error('Failed to add bundle:', error);
    } finally {
      setIsLoading(false);
    }
  };
  
  if (!isOpen) return null;
  
  return (
    
       e.stopPropagation()}>
        {/* Modal header */}
        {bundle.attributes.name}
        <button onClick={onClose}>×</button>
        
        {/* Component selection */}
        {Object.entries(bundle.attributes?.components || {}).map(
          ([componentKey, component]) => (
            
              {component.name} {component.min > 0 && '*'}
              <select
                onChange={(e) => handleComponentSelection(e.target.value, componentKey)}
                required={component.min > 0}
              >
                <option value="">
                  {component.min > 0 ? 'Select an option' : 'None'}
                </option>
                {component.options.map(option => (
                  <option key={option.id} value={option.id}>
                    {getProductName(option.id)}
                  </option>
                ))}
              </select>
            
          )
        )}
        
        {/* Modal actions */}
        <button onClick={onClose} disabled={isLoading}>Cancel</button>
        <button 
          onClick={handleQuickAdd}
          disabled={isLoading || !isConfigurationValid(selectedOptions, bundle)}
        >
          {isLoading ? 'Adding...' : 'Add to Cart'}
        </button>
      
    
  );
}
```

## Performance Optimization

### Lazy Loading Components

```typescript
import dynamic from 'next/dynamic';

// Lazy load heavy patterns
const VisualBuilder = dynamic(
  () => import('./patterns/VisualBuilder'),
  { 
    loading: () => Loading builder...,
    ssr: false // Disable SSR for drag-and-drop
  }
);

// Conditional loading based on viewport
const BundlePattern = ({ pattern, ...props }) => {
  switch (pattern) {
    case 'visual-builder':
      return <VisualBuilder {...props} />;
    case 'wizard':
      return <StepByStepWizard {...props} />;
    default:
      return <CheckboxGrid {...props} />;
  }
};
```

### Optimistic Updates

```typescript
function useOptimisticConfiguration(bundleId: string) {
  const [localConfig, setLocalConfig] = useState({});
  const [serverConfig, setServerConfig] = useState({});
  const [isSyncing, setIsSyncing] = useState(false);
  
  const updateConfiguration = useCallback(async (newConfig) => {
    // Update local state immediately
    setLocalConfig(newConfig);
    
    // Sync with server in background
    setIsSyncing(true);
    try {
      const result = await configureByContextProduct({
        path: { product_id: bundleId },
        body: { data: { selected_options: newConfig } }
      });
      setServerConfig(result.data);
    } catch (error) {
      // Revert on error
      setLocalConfig(serverConfig);
      throw error;
    } finally {
      setIsSyncing(false);
    }
  }, [bundleId, serverConfig]);
  
  return { configuration: localConfig, isSyncing, updateConfiguration };
}
```

## Key Takeaways

1. **Choose patterns based on**:
   - Product complexity
   - User expertise level
   - Device constraints
   - Business goals

2. **Optimize for mobile** when using:
   - Checkbox Grid
   - Accordion View
   - Quick Configure Modal

3. **Enhance engagement** with:
   - Visual Builder
   - Step-by-Step Wizard

4. **Always consider**:
   - Performance optimization
   - Error handling
   - Loading states

## Next Steps

- [Bundle Pricing Strategies](./bundle-pricing-strategies) - Handle dynamic pricing
- [Configure Dynamic Bundles](./configure-dynamic-bundle) - Implementation details
- [Understanding Bundle Configuration](./bundle-configuration-guide) - Deep dive

## References

- [Composable Frontend Examples](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)
- [React DnD Documentation](https://react-dnd.github.io/react-dnd/about)
- [Accessibility Guidelines](https://www.w3.org/WAI/ARIA/apg/patterns/)

---

## Configure Dynamic Bundles

Learn how to implement dynamic bundle configuration in your storefront. For understanding the configuration structure and concepts, see [Understanding Bundle Configuration](./bundle-configuration-guide).

## Prerequisites

Before implementing bundle configuration, ensure you understand:
- [Bundle configuration structure](./bundle-configuration-guide#configuration-structure)
- [Validation requirements](./bundle-configuration-guide#validation)
- How to fetch bundle and component data (see [Get Bundle](./get-bundle))

## Configure Bundle with SDK

Use `configureByContextProduct` to generate a valid bundle configuration:

```typescript
import { configureByContextProduct } from '@epcc-sdk/sdks-shopper';

async function configureDynamicBundle(
  bundleId: string,
  selectedOptions: BundleConfiguration["selected_options"]
) {
  try {
    const response = await configureByContextProduct({
      path: { product_id: bundleId },
      body: {
        data: {
          selected_options: selectedOptions
        }
      }
    });
    
    // Returns configured bundle with updated price
    return {
      success: true,
      configuredBundle: response.data,
      configuration: response.data?.meta?.bundle_configuration
    };
  } catch (error) {
    return {
      success: false,
      error: error.message || 'Failed to configure bundle'
    };
  }
}
```

## Example: Bundle Configurator

Simplified implementation with validation and price updates:

```typescript
function BundleConfigurator({ bundle, componentProducts }) {
  const [selectedOptions, setSelectedOptions] = useState({});
  const [configuredBundle, setConfiguredBundle] = useState(null);
  const [isConfiguring, setIsConfiguring] = useState(false);
  const [validationErrors, setValidationErrors] = useState([]);
  
  const components = bundle.attributes?.components || {};
  
  // Validate and configure on selection change
  useEffect(() => {
    const validation = validateBundleSelection(components, selectedOptions);
    setValidationErrors(validation.errors);
    
    if (validation.isValid && Object.keys(selectedOptions).length > 0) {
      configureBundle();
    }
  }, [selectedOptions]);
  
  const configureBundle = async () => {
    setIsConfiguring(true);
    const result = await configureDynamicBundle(bundle.id, selectedOptions);
    if (result.success) {
      setConfiguredBundle(result.configuredBundle);
    }
    setIsConfiguring(false);
  };
  
  const handleAddToCart = async () => {
    const configuration = configuredBundle?.data?.meta?.bundle_configuration;
    if (!configuration) return;
    
    const cartId = getCartId();
    await manageCarts({
      path: { cartID: cartId },
      body: {
        data: {
          type: 'cart_item',
          id: bundle.id,
          quantity: 1,
          bundle_configuration: configuration
        }
      }
    });
  };
  
  const currentPrice = configuredBundle?.data?.meta?.display_price?.without_tax?.formatted 
    || bundle.meta?.display_price?.without_tax?.formatted;
  
  return (
    <>
      Price: {isConfiguring ? 'Updating...' : currentPrice}
      
      {validationErrors.map((error, idx) => (
        {error}
      ))}
      
      {/* Render component selection UI here */}
      
      <button
        onClick={handleAddToCart}
        disabled={validationErrors.length > 0 || !configuredBundle}
      >
        Add to Cart
      </button>
    </>
  );
}
```

## Configuration Persistence

To improve user experience, you can persist bundle configurations across sessions. See [Configuration Persistence](./bundle-configuration-guide#configuration-persistence) for implementation details including:

- Saving configurations to URL for sharing
- Using localStorage for returning users
- Handling stale configuration data

Example usage in your component:

```typescript
// On mount, restore saved configuration
useEffect(() => {
  const savedConfig = restoreConfigurationFromUrl();
  if (savedConfig) {
    setSelectedOptions(savedConfig);
  }
}, []);

// Save configuration when it changes
useEffect(() => {
  if (Object.keys(selectedOptions).length > 0) {
    saveConfigurationToUrl(bundle.id, selectedOptions);
  }
}, [selectedOptions]);
```

## Error Handling

Common error scenarios to handle:
- **422 Validation Error**: Invalid bundle configuration
- **404 Not Found**: Bundle or component product not found  
- **Stock Issues**: Component out of stock
- **Generic Errors**: Network or server issues

## Implementation Tips

When building bundle configurators:

- **Validate before configuring**: Check selections meet requirements before API calls
- **Debounce API calls**: Wait for user to finish selecting (300-500ms)
- **Show loading states**: Indicate when prices are updating
- **Handle errors gracefully**: Provide clear feedback for validation errors
- **Cache component data**: Component products rarely change

For understanding the configuration data structure and concepts, see [Understanding Bundle Configuration](./bundle-configuration-guide).

## Next Steps

With your bundle configurator implemented:

- [Bundle Pricing Strategies](./bundle-pricing-strategies) - Display dynamic pricing
- [Add Bundle to Cart](./add-bundle-to-cart) - Complete the purchase flow
- [Bundle Selection Patterns](./bundle-selection-patterns) - Advanced UI patterns

## References

- [Configure Bundle API](/docs/api/pxm/catalog/configure-by-context-product)
- [Add to Cart API](/docs/api/carts/manage-carts)
- [Bundle Configuration Guide](/docs/commerce-manager/product-experience-manager/bundles/overview)
- [Composable Frontend Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)

---

## Get Bundle Product Data

Learn how to fetch bundle product details with component products and images for display in your storefront.

## Goal

Fetch complete bundle data including components, images, and inventory for display in your storefront.

## Prerequisites

- Published catalog with bundle products
- Authenticated API access

## Quick Start

```typescript
import { 
  client, 
  getByContextProduct, 
  getByContextComponentProductIds,
  getStock 
} from '@epcc-sdk/sdks-shopper';

// Configure client
client.setConfig({
  baseUrl: 'https://euwest.api.elasticpath.com',
  headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
});

// Fetch bundle with components
async function getBundle(bundleId: string) {
  // Get bundle with component products included
  const response = await getByContextProduct({ 
    path: { product_id: bundleId },
    query: { 
      include: ['component_products', 'main_image', 'files'] 
    }
  });
  
  const bundle = response.data?.data;
  
  // Verify it's a bundle
  if (bundle?.meta?.product_types?.[0] !== 'bundle') {
    throw new Error('Product is not a bundle');
  }
  
  return {
    bundle,
    componentProducts: response.included?.component_products || [],
    mainImage: response.included?.main_images?.[0]
  };
}
```

## Key Concepts

### Bundle Type Detection

The bundle type is available at `bundle.meta?.product_types?.[0]`. To determine if it's fixed or dynamic, check the component requirements:

```typescript
// Check if product is a bundle
if (bundle.meta?.product_types?.[0] === 'bundle') {
  // Determine if fixed or dynamic based on min/max requirements
  const isDynamic = bundle.attributes?.components && 
    Object.values(bundle.attributes.components).some(
      comp => comp.min != null || comp.max != null
    );
}
```

### Fetch Component Configuration

Get detailed component configuration. Both fixed and dynamic bundles have components:

```typescript
async function fetchBundleComponents(bundleId: string) {
  // Get component configuration
  const componentsResponse = await getByContextComponentProductIds({ 
    path: { product_id: bundleId } 
  });
  
  // Structure component data
  const componentData = Object.entries(componentsResponse.data || {}).map(
    ([componentKey, component]) => ({
      key: componentKey,
      id: component.component_id,
      options: component.options.map(opt => ({
        productId: opt.id,
        quantity: opt.quantity || 1,
        type: opt.type,
        sortOrder: opt.sort_order || 0
      })),
      // Include min/max for dynamic bundles
      min: component.min,
      max: component.max,
      name: component.name
    })
  );
  
  return componentData;
}
```

### Component Product Images

Component product images are not included when fetching a bundle. The component products only contain references to their main_image IDs. To efficiently load all component images, use a batch approach:

```typescript
import { getAllFiles } from '@epcc-sdk/sdks-shopper';

async function fetchComponentImages(componentProducts: any[]) {
  // Extract main image IDs from component products
  const mainImageIds = componentProducts
    .map(product => product.relationships?.main_image?.data?.id)
    .filter((id): id is string => typeof id === 'string');
  
  if (mainImageIds.length === 0) {
    return [];
  }
  
  // Fetch all images in one batch request
  const fileResponse = await getAllFiles({
    query: {
      filter: `in(id,${mainImageIds.join(',')})`
    }
  });
  
  return fileResponse.data?.data || [];
}

// Usage with bundle fetch
async function getBundleWithComponentImages(bundleId: string) {
  const response = await getByContextProduct({
    path: { product_id: bundleId },
    query: { include: ['component_products', 'main_image', 'files'] }
  });
  
  const bundle = response.data?.data;
  const componentProducts = response.included?.component_products || [];
  
  // Fetch component images separately
  const componentImages = await fetchComponentImages(componentProducts);
  
  return {
    bundle,
    componentProducts,
    componentImages,
    mainImage: response.included?.main_images?.[0]
  };
}
```

### Check Inventory

Get inventory data for bundle and components:

```typescript
async function fetchBundleInventory(
  bundleId: string, 
  componentProductIds: string[],
  locationId?: string
) {
  // Fetch bundle inventory
  const bundleStock = await getStock({
    path: { product_uuid: bundleId }
  });
  
  // Fetch component inventory
  const componentStockPromises = componentProductIds.map(id =>
    getStock({ path: { product_uuid: id } })
  );
  
  const componentStockResponses = await Promise.allSettled(componentStockPromises);
  
  // Process inventory data
  const inventory = {
    bundle: processBundleStock(bundleStock.data?.data, locationId),
    components: {}
  };
  
  componentStockResponses.forEach((result, index) => {
    if (result.status === 'fulfilled') {
      const productId = componentProductIds[index];
      inventory.components[productId] = processBundleStock(
        result.value.data?.data,
        locationId
      );
    }
  });
  
  return inventory;
}

function processBundleStock(stockData: any, locationId?: string) {
  if (!stockData?.attributes) return null;
  
  const attributes = stockData.attributes;
  
  if (locationId && attributes.locations?.[locationId]) {
    return {
      available: attributes.locations[locationId].available,
      allocated: attributes.locations[locationId].allocated,
      total: attributes.locations[locationId].total
    };
  }
  
  return {
    available: attributes.available,
    allocated: attributes.allocated,
    total: attributes.total
  };
}
```

## Error Handling

```typescript
async function safeFetchBundle(bundleId: string) {
  try {
    const data = await getBundle(bundleId);
    return { success: true, data };
  } catch (error: any) {
    if (error.status === 404) {
      return { success: false, error: 'Bundle not found' };
    }
    if (error.status === 401) {
      return { success: false, error: 'Authentication required' };
    }
    return { success: false, error: 'Failed to load bundle' };
  }
}
```

## Display Example

```typescript
function BundleDisplay({ bundleId }) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    safeFetchBundle(bundleId).then(result => {
      if (result.success) setData(result.data);
      setLoading(false);
    });
  }, [bundleId]);
  
  if (loading) return Loading...;
  if (!data) return Bundle not found;
  
  const { bundle, componentProducts } = data;
  const isDynamic = bundle.attributes?.components && 
    Object.values(bundle.attributes.components).some(
      comp => comp.min != null || comp.max != null
    );
  
  return (
    <>
      {bundle.attributes.name}
      Type: {isDynamic ? 'Dynamic' : 'Fixed'} Bundle
      
      Components:
      
        {componentProducts.map(product => (
          {product.attributes.name}
        ))}
      
    </>
  );
}
```

## Performance Tips

- **Use includes wisely** - Only include data you need
- **Batch image fetching** - Use `getAllFiles` with filter to fetch all component images in one call
- **Cache component images** - Store fetched images to avoid repeated API calls
- **Consider lazy loading** - Load images only when components are visible
- **Cache bundle structure** - Bundle configuration rarely changes
- **Implement loading states** - Show progress during data fetching
- **Handle errors gracefully** - Provide fallbacks for missing images

## Next Steps

- [List Bundle Components](./list-bundle-components) - Deep dive into component fetching
- [Bundle Pricing Strategies](./bundle-pricing-strategies) - Handle bundle pricing
- [Configure Dynamic Bundles](./configure-dynamic-bundle) - Build configuration UI

## References

- [Get Product API](/docs/api/pxm/catalog/get-by-context-product)
- [Component Products API](/docs/api/pxm/catalog/get-by-context-component-product-i-ds)
- [Inventory API](/docs/api/pxm/inventory/get-product-stock)

---

## Handling Bundle Types

Learn how to detect whether a product is a bundle, identify its type (fixed, dynamic, or bundle of bundles), and route to the appropriate handling logic in your storefront.

## Quick Start

```mermaid
flowchart TD
    A[Fetch Product] --> B{"Check product type"}
    B -->|"standard"| C[Display Standard Product]
    B -->|"parent"| D[Display Variation Product]
    B -->|"child"| E[Fetch Parent Product]
    B -->|"bundle"| F[Display Bundle Product]
    
    E --> G[Display with Parent Context]
    F --> H{"Bundle Components?"}
    H -->|"Has Images"| I[Fetch Component Images]
    H -->|"No Images"| J[Display Bundle Form]
    I --> J
    
    style C fill:#E8F5E9,stroke:#4CAF50,color:#000
    style D fill:#E1F5FE,stroke:#0288D1,color:#000
    style G fill:#E1F5FE,stroke:#0288D1,color:#000
    style F fill:#E3F2FD,stroke:#1976D2,color:#000
    style J fill:#E3F2FD,stroke:#1976D2,color:#000
    style E fill:#FFF3E0,stroke:#F57C00,color:#000
    style I fill:#FFF3E0,stroke:#F57C00,color:#000
```

## Bundle Type Detection

Every product has attributes and metadata that help identify its type and configuration:

```typescript
import { getByContextProduct } from '@epcc-sdk/sdks-shopper';

// Fetch any product with necessary includes
const response = await getByContextProduct({
  path: { product_id: productId },
  query: {
    include: ['main_image', 'files', 'component_products']
  }
});

const product = response.data?.data;

// Check product type using meta.product_types
const productType = product?.meta?.product_types?.[0];
const isBundle = productType === 'bundle';
```

### Bundle Type Identification

| Type | Detection Method | Key Characteristics |
|------|------------------|-------------------|
| **Bundle** | `meta.product_types[0] === 'bundle'` | Contains component products |
| **Fixed vs Dynamic** | Check component configuration requirements | Fixed: predefined selections, Dynamic: configurable |
| **Bundle of Bundles** | Component products are also bundles | Navigation container for bundles |

## Routing Based on Product Type

Here's how to properly route products based on their type, following the pattern from the Composable Frontend example:

```typescript
async function ProductPage({ productId }) {
  // Fetch product with all necessary includes
  const response = await getByContextProduct({
    path: { product_id: productId },
    query: { 
      include: ['main_image', 'files', 'component_products'] 
    }
  });

  const productData = response.data?.data;
  if (!productData) return <NotFound />;

  // Route based on meta.product_types
  switch (productData.meta?.product_types?.[0]) {
    case 'standard':
      return <DisplayStandardProduct productData={response.data} />;
      
    case 'parent':
      // Parent product with variations
      return <DisplayVariationProduct productData={response.data} />;
      
    case 'child':
      // Child variant - fetch parent for full context
      const parentResponse = await getByContextProduct({
        path: { product_id: productData.attributes?.base_product_id! },
        query: { include: ['main_image', 'files', 'component_products'] }
      });
      return <DisplayVariationProduct 
        productData={response.data}
        parentProduct={parentResponse.data} 
      />;
      
    case 'bundle':
      // Bundle product - fetch component images if needed
      const componentProducts = response.included?.component_products || [];
      const componentImages = await fetchComponentImages(componentProducts);
      
      return <DisplayBundleProduct 
        productData={response.data}
        componentImages={componentImages}
      />;
      
    default:
      return <DisplayStandardProduct productData={response.data} />;
  }
}
```

## Key Data Structures

### Bundle Product Structure

```typescript
interface BundleProduct {
  id: string;
  type: "product";
  attributes: {
    name: string;
    sku: string;
    // ... other attributes
  };
  meta: {
    product_types: ["bundle"];
    bundle_configuration?: {
      selected_options: BundleConfiguration["selected_options"];
    };
    // ... other meta
  };
}

// Component product includes bundle configuration
interface ComponentProduct {
  id: string;
  type: "product";
  name: string;
  min?: number; // Minimum selections required
  max?: number; // Maximum selections allowed
  sort_order?: number;
  options?: ComponentProductOption[];
}
```

### Component Products Structure

Component products are included when you request them:

```typescript
// Included in the response when using include=['component_products']
interface ComponentProduct {
  id: string;
  type: "product";
  attributes: {
    name: string;
    sku: string;
    price?: Price[];
    commodity_type?: string; // Check for nested bundles
  };
}
```

## Bundle Type Characteristics

### Fixed Bundles

Fixed bundles have components with predefined selections that cannot be changed:

```typescript
function FixedBundle({ product, componentProducts }) {
  // Fixed bundles have components but no shopper configuration
  const hasComponents = componentProducts.length > 0;
  const isConfigurable = componentProducts.some(c => 
    c.min != null || c.max != null
  );
  
  return (
    <>
      {product.attributes.name}
      This bundle includes:
      {/* Display the included components */}
      {hasComponents && componentProducts.map(component => (
        
          {component.attributes.name} - {component.attributes.sku}
        
      ))}
      <AddToCartButton productId={product.id} />
      {/* No configuration needed - predefined selections */}
    </>
  );
}
```

### Dynamic Bundles

Dynamic bundles allow shopper configuration:

```typescript
function DynamicBundle({ product, componentProducts }) {
  const components = product.attributes?.components || {};
  
  const hasRequiredComponents = Object.values(components).some(
    comp => comp.min && comp.min > 0
  );
  
  return (
    <>
      {product.attributes.name}
      {hasRequiredComponents && * Required selections}
      <BundleConfigurator 
        components={components}
        componentProducts={componentProducts}
      />
    </>
  );
}
```

### Bundle of Bundles

Parent bundle containing child bundles:

```typescript
function BundleOfBundles({ product, childBundles }) {
  // Parent bundle is not directly purchasable
  const isNavigational = true;
  
  return (
    <>
      {product.attributes.name}
      This collection includes the following bundles:
      {/* Display child bundle cards in grid */}
      {childBundles.map(bundle => (
        <BundleCard 
          key={bundle.id}
          bundle={bundle}
          link={`/products/${bundle.id}`}
        />
      ))}
    </>
  );
}
```

## When to Fetch Additional Data

### For Dynamic Bundles

When you detect a dynamic bundle, you need:
- Component products for display
- Component images for visual selection
- Inventory data for availability

```typescript
if (product.attributes?.components) {
  // Fetch component product IDs
  const componentIds = await getByContextComponentProductIds({
    path: { product_id: product.id }
  });
  
  // Component products are already included in initial fetch
  // but you may need additional data like images
}
```

### For Bundle of Bundles

Parent bundles need child bundle information:
- Child bundle details
- Individual bundle pricing
- Configuration requirements

```typescript
if (hasChildBundles) {
  // Child bundles are included as component_products
  // Each child needs individual configuration
  const childConfigs = childBundles.map(bundle => ({
    id: bundle.id,
    requiresConfiguration: !!bundle.attributes?.components
  }));
}
```

## Implementation Patterns

### Type-Safe Bundle Handling

```typescript
// Type guard using meta.product_types
function isBundle(product: Product): boolean {
  return product.meta?.product_types?.[0] === 'bundle';
}

// Check for bundle configuration requirements
function hasBundleConfiguration(bundle: Product): boolean {
  // Check if bundle has components that need configuration
  const components = bundle.included?.component_products || [];
  return components.some(component => 
    component.min != null || component.max != null
  );
}

// Type guard for bundle of bundles
function isBundleOfBundles(
  product: Product, 
  componentProducts: Product[]
): boolean {
  if (!isBundle(product)) return false;
  return componentProducts.some(
    cp => cp.meta?.product_types?.[0] === 'bundle'
  );
}

// Usage
const productType = product.meta?.product_types?.[0];

switch (productType) {
  case 'bundle':
    if (hasBundleConfiguration(product)) {
      // Handle dynamic bundle with configuration
    } else if (isBundleOfBundles(product, componentProducts)) {
      // Handle bundle of bundles
    } else {
      // Handle fixed bundle
    }
    break;
  // ... other cases
}
```

### Bundle Router Component

```typescript
export function BundleRouter({ product, componentProducts }) {
  // Determine bundle type and route accordingly
  const bundleType = useMemo(() => {
    if (!isBundle(product)) return 'standard';
    if (isDynamicBundle(product)) return 'dynamic';
    if (isBundleOfBundles(product, componentProducts)) return 'collection';
    return 'fixed';
  }, [product, componentProducts]);
  
  const components = {
    standard: StandardProduct,
    fixed: FixedBundle,
    dynamic: DynamicBundle,
    collection: BundleCollection
  };
  
  const Component = components[bundleType];
  
  return (
    <Component 
      product={product} 
      componentProducts={componentProducts}
    />
  );
}
```

## Key Points to Remember

- **Product type detection** uses `meta.product_types[0]`
- **Bundle products** have type value of `'bundle'`
- **Bundle configuration** is determined by component min/max requirements
- **Component products** must be included in the API request
- **Component images** may need separate fetching for visual selection
- **Each product type** requires different display components

## Common Pitfalls

### Not Including Component Products
```typescript
// ❌ Wrong: Missing component products
const response = await getByContextProduct({
  path: { product_id: productId }
});

// ✅ Correct: Include component products
const response = await getByContextProduct({
  path: { product_id: productId },
  query: { include: ['component_products'] }
});
```

### Not Checking Product Type Correctly
```typescript
// ❌ Wrong: Using old commodity_type field
if (product.commodity_type === 'bundle') {
  showBundleDisplay();
}

// ✅ Correct: Use meta.product_types
if (product.meta?.product_types?.[0] === 'bundle') {
  showBundleDisplay();
}
```

### Not Handling Bundle of Bundles
```typescript
// ❌ Wrong: Trying to add parent bundle to cart
if (isBundleOfBundles) {
  addToCart(parentBundle.id); // This will fail!
}

// ✅ Correct: Navigate to child bundles
if (isBundleOfBundles) {
  showBundleCollection(childBundles);
}
```

## Next Steps

Now that you can detect bundle types:

- **For dynamic bundles**: Continue to [List Bundle Components](./list-bundle-components)
- **For configuration**: See [Configure Dynamic Bundles](./configure-dynamic-bundle)
- **For UI patterns**: Check [Bundle Selection Patterns](./bundle-selection-patterns)

## References

- [Product Types Guide](/docs/commerce-manager/product-experience-manager/products/overview#product-types)
- [Bundle Products API](/docs/api/pxm/products/create-product)
- [Get Product API](/docs/api/pxm/catalog/get-by-context-product)

---

## List Bundle Components

Learn how to fetch bundle component data and display options effectively using the Shopper SDK.

## SDK Functions for Bundles

### getByContextProduct

Fetches a bundle product with its component products:

```typescript
import { getByContextProduct } from '@epcc-sdk/sdks-shopper';

const response = await getByContextProduct({
  path: { 
    product_id: 'BUNDLE_ID' 
  },
  query: {
    include: ['component_products', 'main_image', 'files']
  }
});
```

The response includes:
- Bundle product with `meta.product_types[0] === 'bundle'`
- Component products in `included.component_products`
- Both fixed and dynamic bundles have `attributes.components`
- Dynamic bundles include min/max requirements, fixed bundles do not

### getByContextComponentProductIds

Fetches the component product IDs and their configuration:

```typescript
import { getByContextComponentProductIds } from '@epcc-sdk/sdks-shopper';

const response = await getByContextComponentProductIds({
  path: { 
    product_id: 'BUNDLE_ID' 
  }
});
```

Returns component structure with options and requirements for each component.

## Example: Fetch Bundle with Components

```typescript
async function loadBundleWithComponents(bundleId: string) {
  // Fetch bundle with component products
  const bundleResponse = await getByContextProduct({
    path: { product_id: bundleId },
    query: { 
      include: ['component_products', 'main_image', 'files'] 
    }
  });

  const bundle = bundleResponse.data?.data;
  const componentProducts = bundleResponse.included?.component_products || [];
  const mainImage = bundleResponse.included?.main_images?.[0];
  const allImages = bundleResponse.included?.files || [];

  // Get component configuration details
  const componentConfig = await getByContextComponentProductIds({
    path: { product_id: bundleId }
  });

  return {
    bundle,
    componentProducts,
    componentConfig: componentConfig.data,
    images: {
      main: mainImage,
      all: allImages
    }
  };
}
```

## Displaying Components

Display components with their selection requirements:

```typescript
function BundleComponentDisplay({ bundle, componentProducts }) {
  const components = bundle.attributes?.components || {};
  
  return (
    
      {Object.entries(components).map(([key, component]) => {
        const isDynamic = component.min != null || component.max != null;
        const componentOptions = componentProducts.filter(
          product => component.options.some(opt => opt.id === product.id)
        );
        
        return (
          
            {component.name}
            {isDynamic && (
              Select {component.min || 0} to {component.max || 'any'}
            )}
            
              {componentOptions.map(product => (
                {product.attributes.name}
              ))}
            
          
        );
      })}
    
  );
}
```

## Next Steps

With component data loaded:

- **To implement selection**: Continue to [Configure Dynamic Bundles](./configure-dynamic-bundle)
- **To understand configuration**: See [Understanding Bundle Configuration](./bundle-configuration-guide)
- **To add bundles to cart**: See [Add Bundle to Cart](./add-bundle-to-cart)

## References

- [Get Product API](/docs/api/pxm/catalog/get-by-context-product)
- [Component Products API](/docs/api/pxm/catalog/get-by-context-component-product-i-ds)
- [Inventory API](/docs/api/pxm/inventory/get-product-stock)
- [Composable Frontend Bundle Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)

---

## Bundles Overview

Product bundles allow you to group multiple products together as a single purchasable unit. Elastic Path supports both fixed bundles (predefined selections) and dynamic bundles (shopper-configurable options), enabling powerful cross-sell opportunities and customizable product offerings.

## Common Use Cases

Bundles are ideal for products that are commonly purchased together or benefit from configuration:

- **Computer Builds**: Base unit with configurable RAM, storage, graphics card options
- **Gift Sets**: Curated collections with optional add-ons (gift wrap, cards, premium packaging)
- **Meal Kits**: Base ingredients with optional sides, desserts, or dietary alternatives
- **Camera Packages**: Camera body with lens, bag, and accessory options
- **Furniture Sets**: Sofa with configurable cushions, ottomans, and accent pieces
- **Subscription Boxes**: Core items with customizable preferences

## When to Use Bundles

### Use Bundles When:
- Products are frequently purchased together
- You want to offer bulk discounts on grouped items
- Customers benefit from pre-configured selections
- You need flexible product customization
- Cross-selling complementary products is important
- Managing inventory for component products separately

### Don't Use Bundles When:
- Products have interdependent variations (use [Product Variations](../variations/overview) instead)
- The combination creates a fundamentally different product
- Component products don't make sense individually
- You need more than one level of nesting

## Key Benefits

Using bundles provides several advantages over selling products individually:

- **Increased Average Order Value**: Encourage larger purchases through bundled offerings
- **Simplified Shopping**: Pre-configured options reduce decision fatigue
- **Flexible Customization**: Let shoppers personalize within defined parameters
- **Inventory Efficiency**: Components remain as separate SKUs for easier management
- **Dynamic Pricing**: Offer bundle discounts or calculate prices from components
- **Better User Experience**: Guide customers to complete solutions

## Bundle Types Explained

### Fixed Bundles

Fixed bundles contain a predefined set of products with no shopper customization. They have components but without min/max selection requirements:

```mermaid
graph TD
    B[Camera BundleFixed Configuration] --> C1[Camera BodyCanon R5]
    B --> C2[Lens24-70mm f/2.8]
    B --> C3[Memory Card64GB SD]
    B --> C4[Camera BagProfessional]
    
    style B fill:#E3F2FD,stroke:#1976D2,color:#000
```

**Use Cases**: Starter kits, value packs, curated collections

### Dynamic Bundles

Dynamic bundles allow shoppers to configure their selection. They have components with min and/or max selection requirements:

```mermaid
graph TD
    B[Gaming PC BundleDynamic Configuration] --> Comp1[ProcessorRequired: Choose 1]
    B --> Comp2[Graphics CardRequired: Choose 1]
    B --> Comp3[StorageOptional: Choose 0-2]
    B --> Comp4[AccessoriesOptional: Choose 0-3]
    
    Comp1 --> O1[Intel i7+$300]
    Comp1 --> O2[Intel i9+$500]
    Comp2 --> O3[RTX 4070+$600]
    Comp2 --> O4[RTX 4080+$1200]
    Comp3 --> O5[1TB SSD+$100]
    Comp3 --> O6[2TB SSD+$200]
    Comp4 --> O7[Gaming Mouse+$50]
    Comp4 --> O8[Mechanical Keyboard+$150]
    
    classDef bundle fill:#E3F2FD,stroke:#1976D2,color:#000
    classDef component fill:#FFF3E0,stroke:#F57C00,color:#000
    classDef option fill:#E8F5E9,stroke:#4CAF50,color:#000
    
    class B bundle
    class Comp1,Comp2,Comp3,Comp4 component
    class O1,O2,O3,O4,O5,O6,O7,O8 option
```

**Component Types**:
- **Required**: Must select specified number of options
- **Optional**: Can skip or select up to maximum
- **Multi-select**: Can choose multiple options with min/max limits

### Bundle of Bundles

One level of bundle nesting for complex product hierarchies:

```mermaid
graph TD
    P[Home Office CollectionParent Bundle] --> B1[Desk BundleConfigurable]
    P --> B2[Chair BundleConfigurable]
    P --> B3[Storage BundleConfigurable]
    
    B1 --> D1[Desk Options...]
    B2 --> C1[Chair Options...]
    B3 --> S1[Storage Options...]
    
    style P fill:#FCE4EC,stroke:#C2185B,color:#000
```

**Important**: Each child bundle is configured and purchased separately

## Frontend Implementation Overview

When building bundle selection in your storefront, consider these critical aspects:

### Component Selection Flow
```mermaid
flowchart TD
    A[Display Bundle] --> B[Show Components]
    B --> C{Component Type?}
    C -->|Required| D[Force Selection]
    C -->|Optional| E[Allow Skip]
    C -->|Multi| F[Check Min/Max]
    D --> G[Validate All Required]
    E --> G
    F --> G
    G --> H{Valid?}
    H -->|Yes| I[Update Price]
    H -->|No| J[Show Errors]
    I --> K[Enable Add to Cart]
    J --> B
    
    classDef start fill:#E3F2FD,stroke:#1976D2,color:#000
    classDef process fill:#FFF9C4,stroke:#F9A825,color:#000
    classDef decision fill:#F5F5F5,stroke:#757575,color:#000
    classDef success fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef error fill:#FFCDD2,stroke:#D32F2F,color:#000
    
    class A start
    class B,D,E,F,G process
    class C,H decision
    class I,K success
    class J error
```

### Key Data Structures

Understanding bundle data is crucial for implementation:

```typescript
// Bundle product structure
interface BundleProduct {
  id: string
  type: "bundle"
  attributes: {
    name: string
    components: {
      [key: string]: ComponentProduct
    }
  }
  meta: {
    product_types: string[]  // First element indicates type: 'bundle'
    bundle_configuration?: {
      selected_options: BundleConfiguration["selected_options"]
    }
  }
}

// Component structure
interface ComponentProduct {
  name: string
  options: ComponentProductOption[]
  min?: number  // Minimum selections required
  max?: number  // Maximum selections allowed
  sort_order?: number
}

// Component option structure
interface ComponentProductOption {
  id: string
  quantity?: number
  type: 'product'
  sort_order?: number
}

// Selected configuration
interface BundleConfiguration {
  selected_options: {
    [componentKey: string]: {
      [optionId: string]: number  // quantity
    }
  }
}
```

### Critical Implementation Points

#### Configuration State Management
- Bundle configuration must be sent when adding to cart
- Use `configureByContextProduct` API to validate selections
- Configuration affects final price calculation

#### Price Updates
- Dynamic bundles require real-time price recalculation
- Show loading states during price updates
- Handle both explicit and auto-pricing models

#### Validation Requirements
- Enforce min/max selection rules per component
- Validate all required components have selections
- Provide clear error messaging for invalid configurations

#### Cart Operations
- Bundle configuration is required for dynamic bundles
- Each bundle in cart maintains its configuration
- Bundle components are tracked separately for inventory

## Bundle Pricing Models

### Explicit Pricing
Bundle has a fixed price regardless of component selection:
```typescript
// Bundle price set in PXM
bundle.attributes.price = {
  USD: { amount: 99900, includes_tax: false }
}
```

### Auto/Cumulative Pricing
Total calculated from selected component prices:
```typescript
// Price updates based on selection
const totalPrice = selectedComponents.reduce(
  (sum, component) => sum + component.price * component.quantity,
  0
)
```

For detailed pricing implementation, see [Bundle Pricing Strategies](./bundle-pricing-strategies).

## Common Frontend Patterns

Choose the right selection pattern based on your needs:

| Pattern | Best For | Complexity |
|---------|----------|------------|
| **Checkbox Grid** | Visual products, quick selection | 🟢 Simple |
| **Step-by-Step Wizard** | Complex bundles, guided experience | 🟡 Moderate |
| **Accordion View** | Many components, space-constrained | 🟢 Simple |
| **Visual Builder** | Customizable products, drag-drop | 🔴 Complex |

For implementation examples and code, see [Bundle Selection Patterns](./bundle-selection-patterns).

## Common Frontend Pitfalls

Avoid these common mistakes when implementing bundles:

### 1. Not Validating Component Requirements
```typescript
// ❌ Wrong: Adding to cart without validation
addToCart(bundleId, configuration);

// ✅ Correct: Validate requirements first
if (validateBundleConfiguration(components, configuration)) {
  addToCart(bundleId, configuration);
}
```

### 2. Ignoring Price Update States
```typescript
// ❌ Wrong: No feedback during price calculation
updateConfiguration(newConfig);

// ✅ Correct: Show loading state
setIsPriceUpdating(true);
const updatedBundle = await configureBundle(newConfig);
setIsPriceUpdating(false);
```

### 3. Not Handling Configuration Persistence
```typescript
// ❌ Wrong: Configuration lost on page refresh

// ✅ Correct: Persist to URL or session
const configString = btoa(JSON.stringify(configuration));
router.push(`/bundle/${bundleId}?config=${configString}`);
```

### 4. Forgetting Error States
```typescript
// ❌ Wrong: Silent failures
const result = await addBundleToCart(data);

// ✅ Correct: Handle errors explicitly
try {
  const result = await addBundleToCart(data);
  showSuccess("Bundle added to cart!");
} catch (error) {
  showError("Failed to add bundle. Please check your selections.");
}
```

## Troubleshooting

### Common Issues and Solutions

#### "Bundle configuration is required" error
- **Cause**: Attempting to add dynamic bundle without configuration
- **Solution**: Ensure `bundle_configuration` is included in cart request

#### Price not updating with selection changes
- **Cause**: Not calling configure API after selection change
- **Solution**: Use `configureByContextProduct` after each change

#### Component products not showing
- **Cause**: Missing includes, unpublished catalog, or incorrect product type detection
- **Solution**: Ensure catalog is published, use proper includes, and check products with `meta.product_types[0] === 'bundle'`

#### Validation errors not showing
- **Cause**: Not checking component min/max requirements
- **Solution**: Implement client-side validation before API calls

## Learning Path

Follow this recommended path to master bundle implementation:

1. **[Handling Bundle Types](./handling-bundle-types)**  
   Learn to detect and handle different bundle types
   
2. **[Get Bundle Product Data](./get-bundle)**  
   Fetch bundle data with components and images
   
3. **[List Bundle Components](./list-bundle-components)**  
   Display bundle components with their options
   
4. **[Configure Dynamic Bundles](./configure-dynamic-bundle)**  
   Implement component selection and configuration
   
5. **[Understanding Bundle Configuration](./bundle-configuration-guide)** *(Advanced)*  
   Deep dive into configuration structure and validation
   
6. **[Bundle Selection Patterns](./bundle-selection-patterns)**  
   Choose and implement the best UI pattern for your needs
   
7. **[Bundle Pricing Strategies](./bundle-pricing-strategies)**  
   Understand pricing models and display dynamic prices
   
8. **[Add Bundle to Cart](./add-bundle-to-cart)**  
   Complete the purchase flow with bundle configuration

## Next Steps

### How-To Guides
- [Handling Bundle Types](./handling-bundle-types) - Detect and route bundle types
- [Bundle Selection Patterns](./bundle-selection-patterns) - UI/UX implementation patterns
- [Get Bundle Product Data](./get-bundle) - Fetch bundle and component data
- [Configure Dynamic Bundles](./configure-dynamic-bundle) - Build configuration UI

### Related Topics
- [Product Variations](../variations/overview)
- [Cart Management](/docs/developer-tools/fundamentals/cart/overview)
- [Inventory Management](/docs/api/pxm/inventory/inventory)

## References

- [Bundles API Guide](/docs/api/pxm/products/create-product)
- [Dynamic Bundles Guide](/docs/commerce-manager/product-experience-manager/bundles/overview)
- [Composable Frontend Bundle Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)
- [Bundle Configuration API](/docs/api/pxm/catalog/configure-by-context-product)

---

## Retrieving Product Details


This guide shows you how to fetch and display detailed product information for individual product pages, including images, pricing, inventory, and SEO metadata.

## Fetch a single product

Use the `getByContextProduct` function to retrieve detailed information for a specific product:

```javascript
import { getByContextProduct } from "@epcc-sdk/sdks-shopper"

const response = await getByContextProduct({
  path: { product_id: productId },
  query: { include: ["main_image"] },
})

const product = response.data?.data
const mainImages = response.data?.included?.main_images || []
```

## Handle missing products

Check if the product exists and handle the not found case:

```javascript
import { notFound } from "next/navigation"

export default async function ProductPage({ params }) {
  const response = await getByContextProduct({
    path: { product_id: params.id },
    query: { include: ["main_image"] },
  })

  if (!response.data) {
    notFound()
  }

  const product = response.data.data
  // Continue with product display...
}
```

## Extract product information

Safely extract product attributes with fallback values:

```javascript
import { extractProductImage } from "@epcc-sdk/sdks-shopper"

const name = product.attributes?.name || "Unnamed Product"
const description = product.attributes?.description || "No description available"
const sku = product.attributes?.sku || "No SKU"

const mainImage = extractProductImage(product, mainImages)
const imageUrl = mainImage?.link?.href || "/placeholder.jpg"
```

## Extract pricing information

Get product pricing with support for sale prices:

```javascript
// Extract pricing information
const priceData = product.meta?.display_price?.without_tax

// Enhance price data with original price if available
if (priceData && product.meta?.original_price) {
  priceData.original_price = product.meta.original_price.without_tax?.amount
}
```

## Display product pricing

Create a component to show pricing with sale price handling:

```jsx
function ProductPrice({ priceData }) {
  if (!priceData) {
    return Price not available
  }

  const currentPrice = priceData.amount
  const originalPrice = priceData.original_price
  const currency = priceData.currency
  const isOnSale = originalPrice && originalPrice > currentPrice

  const formatPrice = (amount) => {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: currency,
    }).format(amount / 100)
  }

  return (
    
      
        {formatPrice(currentPrice)}
      
      {isOnSale && (
        
          {formatPrice(originalPrice)}
        
      )}
    
  )
}
```

## Generate SEO metadata

Create dynamic metadata for better search engine visibility:

```javascript
export async function generateMetadata({ params }) {
  const response = await getByContextProduct({
    path: { product_id: params.id },
    query: { include: ["main_image"] },
  })

  if (!response.data) {
    return {
      title: "Product Not Found",
    }
  }

  const product = response.data.data
  const mainImage = extractProductImage(
    product,
    response.data.included?.main_images || []
  )
  
  const name = product.attributes?.name || "Unnamed Product"
  const description = product.attributes?.description || "No description available"
  const imageUrl = mainImage?.link?.href || "/placeholder.jpg"

  return {
    title: name,
    description: description,
    openGraph: {
      title: name,
      description: description,
      images: [imageUrl],
      type: "website",
    },
    twitter: {
      card: "summary_large_image",
      title: name,
      description: description,
      images: [imageUrl],
    },
  }
}
```

## Add structured data

Include JSON-LD structured data for rich search results:

```javascript
// Create structured data for SEO
const productJsonLd = {
  "@context": "https://schema.org",
  "@type": "Product",
  name,
  description,
  sku,
  image: imageUrl,
}

// Add price information if available
if (priceData) {
  productJsonLd.offers = {
    "@type": "Offer",
    price: priceData.amount / 100,
    priceCurrency: priceData.currency,
  }
}
```

## Build product detail layout

Create a responsive product detail page layout:

```jsx
import Image from "next/image"
import Link from "next/link"

export default function ProductDetail({ product, mainImage, priceData }) {
  const name = product.attributes?.name || "Unnamed Product"
  const description = product.attributes?.description || ""
  const sku = product.attributes?.sku || "No SKU"
  const imageUrl = mainImage?.link?.href || "/placeholder.jpg"

  return (
    
      <Link href="/" className="inline-block mb-6 text-blue-600 hover:underline">
        ← Back to products
      </Link>

      
        
          <Image
            src={imageUrl}
            alt={name}
            fill
            sizes="(max-width: 768px) 100vw, 50vw"
            className="object-contain"
          />
        

        
          {name}
          SKU: {sku}

          
            <ProductPrice priceData={priceData} />
          

          
            Description
            {description}
          
        
      
    
  )
}
```

## Handle inventory display

Integrate inventory levels into the product detail page:

```jsx
import { fetchInventoryLocations, fetchProductStock } from "../lib/inventory"
import { MultiLocationInventory } from "./components"

export default async function ProductPage({ params }) {
  const response = await getByContextProduct({
    path: { product_id: params.id },
    query: { include: ["main_image"] },
  })

  if (!response.data) {
    notFound()
  }

  const product = response.data.data

  // Fetch inventory data in parallel for better performance
  const [inventoryLocations, productStock] = await Promise.all([
    fetchInventoryLocations(),
    fetchProductStock(product.id),
  ])

  return (
    
      {/* Product layout */}
      
        {/* Product image */}
        
          <Image
            src={imageUrl}
            alt={name}
            fill
            className="object-contain"
          />
        

        
          {name}
          
          {/* Price and inventory */}
          
            <ProductPrice priceData={priceData} />
            <MultiLocationInventory
              stock={productStock}
              locations={inventoryLocations}
              className="text-sm mt-1"
            />
          

          {/* Description */}
          
            Description
            {description}
          
        
      
    
  )
}
```

## Complete implementation

Here's a complete product detail page with all features:

```jsx
import {
  getByContextProduct,
  extractProductImage,
} from "@epcc-sdk/sdks-shopper"
import Image from "next/image"
import Link from "next/link"
import { notFound } from "next/navigation"
import { Metadata } from "next"
import {
  ProductPrice,
  MultiLocationInventory,
} from "../../components"
import {
  fetchInventoryLocations,
  fetchProductStock,
  getStructuredDataAvailability,
} from "../../../lib/inventory"

export async function generateMetadata({ params }) {
  const response = await getByContextProduct({
    path: { product_id: params.id },
    query: { include: ["main_image"] },
  })

  if (!response.data) {
    return { title: "Product Not Found" }
  }

  const product = response.data.data
  const mainImage = extractProductImage(
    product,
    response.data.included?.main_images || []
  )
  
  const name = product.attributes?.name || "Unnamed Product"
  const description = product.attributes?.description || "No description available"
  const imageUrl = mainImage?.link?.href || "/placeholder.jpg"

  return {
    title: name,
    description: description,
    openGraph: {
      title: name,
      description: description,
      images: [imageUrl],
      type: "website",
    },
    twitter: {
      card: "summary_large_image",
      title: name,
      description: description,
      images: [imageUrl],
    },
  }
}

export default async function ProductPage({ params }) {
  const response = await getByContextProduct({
    path: { product_id: params.id },
    query: { include: ["main_image"] },
  })

  if (!response.data) {
    notFound()
  }

  const product = response.data.data
  const mainImage = extractProductImage(
    product,
    response.data.included?.main_images || []
  )
  
  const name = product.attributes?.name || "Unnamed Product"
  const description = product.attributes?.description || "No description available"
  const sku = product.attributes?.sku || "No SKU"
  const imageUrl = mainImage?.link?.href || "/placeholder.jpg"

  // Extract pricing information
  const priceData = product.meta?.display_price?.without_tax

  // Enhance price data with original price if available
  if (priceData && product.meta?.original_price) {
    priceData.original_price = product.meta.original_price.without_tax?.amount
  }

  // Fetch inventory data in parallel
  const [inventoryLocations, productStock] = await Promise.all([
    fetchInventoryLocations(),
    fetchProductStock(product.id),
  ])

  // Create structured data for SEO
  const productJsonLd = {
    "@context": "https://schema.org",
    "@type": "Product",
    name,
    description,
    sku,
    image: imageUrl,
  }

  // Add price and stock information to structured data
  if (priceData) {
    const stockAvailability = productStock
      ? getStructuredDataAvailability({
          available: productStock.attributes.available,
          allocated: productStock.attributes.allocated,
          total: productStock.attributes.total,
        })
      : "https://schema.org/OutOfStock"

    productJsonLd.offers = {
      "@type": "Offer",
      price: priceData.amount / 100,
      priceCurrency: priceData.currency,
      availability: stockAvailability,
    }
  }

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(productJsonLd) }}
      />
      
        <main className="max-w-5xl mx-auto bg-white p-6 rounded shadow-sm">
          <Link
            href="/"
            className="inline-block mb-6 text-blue-600 hover:underline"
          >
            ← Back to products
          </Link>

          
            
              <Image
                src={imageUrl}
                alt={name}
                fill
                sizes="(max-width: 768px) 100vw, 50vw"
                className="object-contain"
              />
            

            
              {name}
              SKU: {sku}

              
                <ProductPrice priceData={priceData} />
                <MultiLocationInventory
                  stock={productStock}
                  locations={inventoryLocations}
                  className="text-sm mt-1"
                />
              

              
                Description
                {description}
              
            
          
        </main>
      
    </>
  )
}
```

## Add error handling

Create a not found page for missing products:

```jsx
// not-found.tsx
import Link from "next/link"

export default function NotFound() {
  return (
    
      
        
          Product Not Found
        
        
          The product you're looking for doesn't exist or has been removed.
        
        <Link
          href="/"
          className="inline-block bg-blue-600 text-white px-6 py-2 rounded hover:bg-blue-700"
        >
          Back to Products
        </Link>
      
    
  )
}
```

:::tip
See the complete [list-products example](https://github.com/elasticpath/composable-frontend/tree/main/examples/list-products) on GitHub for a full implementation with authentication, error handling, and multi-location inventory.
:::

---

## InstantSearch Adapter


This guide shows you how to use the `@elasticpath/catalog-search-instantsearch-adapter` package to build search experiences in your storefront using the popular [InstantSearch.js](https://github.com/algolia/instantsearch) library.

The adapter translates InstantSearch.js requests into Catalog Search API requests and transforms the responses back into InstantSearch format, giving you access to a rich ecosystem of pre-built search widgets.

:::tip
Before using the adapter, ensure you have Catalog Search enabled for your store. See [Catalog Search in Commerce Manager](/docs/commerce-manager/product-experience-manager/catalog-search/overview) to get started.
:::

## Features

- Seamless integration with InstantSearch.js widgets
- Full-text search with highlighting
- Faceted search and filtering
- Pagination and result sorting
- Support for both vanilla JavaScript and React InstantSearch

## Installation

Install the adapter along with the Elastic Path SDK and InstantSearch.js:

```bash
npm install @elasticpath/catalog-search-instantsearch-adapter @epcc-sdk/sdks-shopper instantsearch.js
```

For React applications:

```bash
npm install @elasticpath/catalog-search-instantsearch-adapter @epcc-sdk/sdks-shopper react-instantsearch instantsearch.js
```

## Basic usage

### Configure the client

First, configure the Elastic Path shopper client with your credentials:

```javascript
import { configureClient, client } from '@epcc-sdk/sdks-shopper';

configureClient(
  {
    baseUrl: 'https://euwest.api.elasticpath.com',
  },
  {
    clientId: 'YOUR_CLIENT_ID',
    storage: 'localStorage', // Optional: persist tokens
  }
);
```

### Create the adapter

Create an instance of the adapter with your configured client:

```javascript
import CatalogSearchInstantSearchAdapter from '@elasticpath/catalog-search-instantsearch-adapter';

const catalogSearchAdapter = new CatalogSearchInstantSearchAdapter({
  client: client,
});
```

### Initialize InstantSearch

Use the adapter's `searchClient` property when initializing InstantSearch:

```javascript
import instantsearch from 'instantsearch.js';

const search = instantsearch({
  indexName: 'search',
  searchClient: catalogSearchAdapter.searchClient,
});

// Add widgets
search.addWidgets([
  instantsearch.widgets.searchBox({
    container: '#searchbox',
  }),
  instantsearch.widgets.hits({
    container: '#hits',
  }),
  instantsearch.widgets.refinementList({
    container: '#brand-list',
    attribute: 'extensions.products(product_brands).name',
  }),
]);

search.start();
```

## React integration

For React applications, use the `react-instantsearch` package:

```jsx
import React from 'react';
import {
  InstantSearch,
  SearchBox,
  Hits,
  RefinementList,
  Pagination,
} from 'react-instantsearch';
import CatalogSearchInstantSearchAdapter from '@elasticpath/catalog-search-instantsearch-adapter';
import { configureClient, client } from '@epcc-sdk/sdks-shopper';

// Configure authentication (typically done once in your app initialization)
configureClient(
  {
    baseUrl: 'https://euwest.api.elasticpath.com',
  },
  {
    clientId: 'YOUR_CLIENT_ID',
    storage: 'localStorage',
  }
);

// Create the adapter
const catalogSearchAdapter = new CatalogSearchInstantSearchAdapter({
  client: client,
});

function Search() {
  return (
    <InstantSearch 
      indexName="search" 
      searchClient={catalogSearchAdapter.searchClient}
    >
      <SearchBox />
      
        
          <RefinementList attribute="extensions.products(product_brands).name" />
        
        
          <Hits />
          <Pagination />
        
      
    </InstantSearch>
  );
}
```

## Index name configuration

The `indexName` parameter determines which Elastic Path search endpoint to use:

| Index Name | Usage |
|------------|-------|
| `search` | Regular product search (required) |
| `autocomplete` | Autocomplete and suggestions |

These values map directly to the `type` parameter in Elastic Path's Catalog Search API.

## Supported widgets

The adapter supports most InstantSearch widgets out of the box.

### Search widgets

- `searchBox` - Basic search input
- `autocomplete` - Search with suggestions (use with `indexName: 'autocomplete'`)
- `voiceSearch` - Voice input support

### Results widgets

- `hits` - Display search results
- `infiniteHits` - Infinite scrolling results
- `highlight` - Highlight matching terms
- `snippet` - Show text snippets

### Filtering widgets

- `refinementList` - Filter by facet values
- `hierarchicalMenu` - Category navigation
- `rangeSlider` / `rangeInput` - Numeric range filters
- `toggleRefinement` - Boolean filters
- `clearRefinements` - Clear all filters
- `currentRefinements` - Show active filters

### Pagination widgets

- `pagination` - Page navigation
- `hitsPerPage` - Results per page selector

### Metadata widgets

- `stats` - Search statistics
- `breadcrumb` - Navigation breadcrumb

### Widgets with limitations

- `geoSearch` - Not supported (Catalog Search does not support geo-search)
- `queryRuleCustomData` - Limited support
- `sortBy` - Use `configure` widget with `additionalSearchParameters.sort_by`

## Widget examples

### Hierarchical categories

```javascript
instantsearch.widgets.hierarchicalMenu({
  container: '#categories',
  attributes: [
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
  ],
});
```

### Price range filter

```javascript
instantsearch.widgets.rangeSlider({
  container: '#price-range',
  attribute: 'price.float_price',
});
```

### Searchable refinement list

```javascript
instantsearch.widgets.refinementList({
  container: '#brands',
  attribute: 'extensions.products(product_brands).name',
  limit: 10,
  showMore: true,
  showMoreLimit: 50,
  searchable: true,
  searchablePlaceholder: 'Search brands',
});
```

## Union search

The adapter supports union search to query multiple collections simultaneously:

```javascript
const adapter = new CatalogSearchInstantSearchAdapter({
  client: client,
  union: true,
});
```

## Migrating from Algolia

If you're migrating from Algolia to Elastic Path Catalog Search, most of your InstantSearch implementation will work without changes:

1. Replace the Algolia search client with this adapter
2. Update attribute names to match your Elastic Path catalog structure
3. Configure authentication using the Elastic Path SDK instead of Algolia API keys

## Related guides

- [Catalog Search Overview](/docs/commerce-manager/product-experience-manager/catalog-search/overview) - Enable and configure Catalog Search
- [Indexing](/docs/commerce-manager/product-experience-manager/catalog-search/indexing) - Configure searchable fields
- [Profiles](/docs/commerce-manager/product-experience-manager/catalog-search/profiles) - Set up search profiles
- [Setting Up Catalog Search (API)](/guides/How-To/Catalogs/Search/setting-up-search) - API-based configuration

:::tip
See the complete [InstantSearch example](https://github.com/elasticpath/composable-frontend/tree/main/examples/spa-search-instantsearch) on GitHub for a full implementation.
:::

---

## List Products


This guide shows you how to fetch and display a list of products from your Elastic Path Commerce Cloud store.

:::tip
Before using the SDK to fetch products, make sure you've set up authentication. See the [Authentication Quick Start](../../authentication/quickstart.mdx) guide to configure your credentials and SDK setup.
:::

## Basic product listing

### Fetch all products

Use the `getByContextAllProducts` function to retrieve all products from your store:

```javascript
import { getByContextAllProducts } from "@epcc-sdk/sdks-shopper"

const response = await getByContextAllProducts({
  query: {
    include: ["main_image"],
  },
})

const products = response.data?.data || []
const productMainImages = response.data?.included?.main_images || []
```

The `include` parameter fetches product images alongside the basic product data, which you'll need for displaying product cards.

### Extract product images

Use the `extractProductImage` helper to safely access product images:

```javascript
import { extractProductImage } from "@epcc-sdk/sdks-shopper"

// Extract the main image for a product
const mainImage = extractProductImage(product, productMainImages)
const imageUrl = mainImage?.link?.href || "/placeholder.jpg"

// The extractProductImage function finds the matching image by ID:
const extractProductImage = (product, images) => {
  return images?.find((file) => {
    if (file.id === product.relationships?.main_image?.data?.id) {
      return file
    }
  })
}
```

### Handle empty states and errors

Always check for empty results and handle errors gracefully:

```javascript
try {
  const response = await getByContextAllProducts({
    query: {
      include: ["main_image"],
    },
  })

  // Check for errors
  if (!response.data) {
    throw new Error("Failed to fetch products")
  }

  const products = response.data?.data || []
  const productMainImages = response.data?.included?.main_images || []

  // Handle empty results
  if (products.length === 0) {
    return { products: [], message: "No products found" }
  }

  return { products, productMainImages }
} catch (error) {
  console.error("Error fetching products:", error)
  throw new Error("Unable to load products. Please try again.")
}
```

## Pagination

### Add pagination

Handle large product catalogs with pagination using `page[limit]` and `page[offset]` parameters:

```javascript
const page = 1 // Current page number
const limit = 20 // Items per page

const response = await getByContextAllProducts({
  query: {
    include: ["main_image"],
    "page[limit]": BigInt(limit),        // Maximum items to return (1-100)
    "page[offset]": BigInt((page - 1) * limit), // Number of items to skip
  },
})

// Extract pagination metadata from response
const resultsInfo = response.data?.meta?.results
const totalCount = Number(resultsInfo?.total) || 0
const totalPages = Math.ceil(totalCount / limit)
const hasNextPage = page < totalPages
const hasPreviousPage = page > 1
```

**Pagination Options:**
- `page[limit]`: Maximum number of items to return (1-100, default: 25)
- `page[offset]`: Number of items to skip for pagination
- Response includes `meta.results.total` for total item count

## Filtering

### Add product filtering

Filter products using Elastic Path's filtering syntax with exact matches and multiple value support:

```javascript
// Available filter options
const filters = {
  name: "Blue Shirt",           // Exact product name match
  sku: "SHIRT-001",            // Exact SKU match
  productTypes: ["parent", "child"], // Match multiple product types
}

// Build filter query string
function buildFilterQuery(filters) {
  const filterParts = []

  // Name filter - exact match only
  if (filters.name?.trim()) {
    filterParts.push(`eq(name,${filters.name.trim()})`)
  }

  // SKU filter - exact match only
  if (filters.sku?.trim()) {
    filterParts.push(`eq(sku,${filters.sku.trim()})`)
  }

  // Product types - supports multiple values
  if (filters.productTypes?.length > 0) {
    if (filters.productTypes.length === 1) {
      filterParts.push(`eq(product_types,${filters.productTypes[0]})`)
    } else {
      filterParts.push(`in(product_types,${filters.productTypes.join(',')})`)
    }
  }

  return filterParts.length > 0 ? { filter: filterParts.join(',') } : {}
}

// Apply filters to API call
const filterQuery = buildFilterQuery(filters)
const response = await getByContextAllProducts({
  query: {
    include: ["main_image"],
    ...filterQuery,
  },
})
```

**Available Filters:**
- `eq(name,value)`: Exact product name match
- `eq(sku,value)`: Exact SKU match
- `eq(product_types,value)`: Single product type match
- `in(product_types,value1,value2)`: Multiple product types match
- Multiple filters combined with commas: `eq(name,value),eq(sku,value)`

**Common Product Types:**
- `parent`: Parent products with variations
- `child`: Child products (variations)
- `bundle`: Product bundles
- `standalone`: Individual products

## Advanced usage

### Combine pagination, filtering, and sorting

Use both pagination and filtering together for complete product catalog management:

```javascript
export default async function ProductsPage({ searchParams }) {
  const params = await searchParams
  
  // Parse pagination parameters
  const page = parseInt(params.page || "1", 10)
  const limit = Math.min(parseInt(params.limit || "20", 10), 100) // Cap at 100
  
  // Parse filter parameters from URL
  const filters = {
    name: params.name || "",
    sku: params.sku || "",
    productTypes: params.product_types ? params.product_types.split(',') : []
  }
  
  // Build filter query
  const filterQuery = buildFilterQuery(filters)

  // Fetch products with both pagination and filtering
  const response = await getByContextAllProducts({
    query: {
      include: ["main_image"],
      "page[limit]": BigInt(limit),
      "page[offset]": BigInt((page - 1) * limit),
      ...filterQuery,
    },
  })

  const products = response.data?.data || []
  const productMainImages = response.data?.included?.main_images || []
  
  // Extract pagination metadata
  const resultsInfo = response.data?.meta?.results
  const totalCount = Number(resultsInfo?.total) || 0
  const totalPages = Math.ceil(totalCount / limit)
  
  return (
    
      Showing {products.length} of {totalCount} products
      Page {page} of {totalPages}
      {/* Render products and pagination controls */}
    
  )
}
```

**Key Benefits:**
- **URL-based state**: Pagination and filters persist in URL for sharing/bookmarking
- **Performance**: Only fetch needed items with pagination
- **Flexibility**: Combine any filters with pagination
- **Metadata**: Access total counts and pagination info from API response

## Performance optimization

### Limit included resources

Only include the resources you need to improve performance:

```javascript
// Only include main image for basic listing
const response = await getByContextAllProducts({
  query: {
    include: ["main_image"],
    "page[limit]": BigInt(20),
  },
})
```

### Cache product data

For frequently accessed product lists, consider caching:

```javascript
// Example with Next.js unstable_cache
import { unstable_cache } from 'next/cache'

const getCachedProducts = unstable_cache(
  async () => {
    const response = await getByContextAllProducts({
      query: {
        include: ["main_image"],
        "page[limit]": BigInt(50),
      },
    })
    return response.data
  },
  ['products-list'],
  {
    revalidate: 300, // 5 minutes
    tags: ['products']
  }
)
```

## User experience enhancements

### Loading states

Show loading indicators while fetching products:

```javascript
// React component example
function ProductList() {
  const [products, setProducts] = useState([])
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)

  useEffect(() => {
    const fetchProducts = async () => {
      try {
        setLoading(true)
        const response = await getByContextAllProducts({
          query: { include: ["main_image"] },
        })
        setProducts(response.data?.data || [])
      } catch (err) {
        setError("Failed to load products")
      } finally {
        setLoading(false)
      }
    }

    fetchProducts()
  }, [])

  if (loading) return Loading products...
  if (error) return Error: {error}
  if (products.length === 0) return No products found

  return (
    
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    
  )
}
```

### SEO optimization

Optimize product listing pages for search engines:

```javascript
// Next.js metadata generation
export async function generateMetadata({ searchParams }) {
  const params = await searchParams
  const page = parseInt(params.page || "1", 10)
  const filters = params.name || ""
  
  let title = "Products"
  let description = "Browse our product catalog"
  
  if (filters) {
    title = `${filters} - Products`
    description = `Find ${filters} products in our catalog`
  }
  
  if (page > 1) {
    title += ` - Page ${page}`
  }

  return {
    title,
    description,
    robots: {
      index: true,
      follow: true,
    },
  }
}
```

## Related guides

- [Get Product Details](./get-product-details.mdx) - Fetch detailed product information
- [Product Variations](./variations/overview) - Work with parent and child products
- [Authentication Quick Start](../../authentication/quickstart.mdx) - Set up SDK authentication

:::tip
See the complete [list-products example](https://github.com/elasticpath/composable-frontend/tree/main/examples/list-products) on GitHub for a full implementation with authentication, error handling, pagination, and filtering.
:::

---

## Handling Product Types

Learn how to detect whether a product is standard, parent, or child, and route to the appropriate handling logic.

## Quick Start

```mermaid
flowchart TD
    A[Fetch Product] --> B{"Check product type"}
    B -->|"standard"| C[Display as regular product]
    B -->|"parent"| D[Show variation selector]
    B -->|"child"| E[Fetch parent for context]
    E --> F[Pre-select current options]
    
    style C fill:#E8F5E9,stroke:#4CAF50,color:#000
    style D fill:#E3F2FD,stroke:#1976D2,color:#000
    style F fill:#FFF3E0,stroke:#FF9800,color:#000
```

## Product Type Detection

Every product has a type accessible via `meta.product_types[0]`:

```typescript
import { getByContextProduct } from '@epcc-sdk/sdks-shopper';

// Fetch product with necessary includes
const response = await getByContextProduct({
  path: { product_id: productId },
  query: {
    include: ['main_image', 'files']
  }
});

// Detect product type
const productType = response.data?.data?.meta?.product_types?.[0];
```

### Product Type Values

| Type | Description | Can Add to Cart | Has Variations |
|------|-------------|-----------------|----------------|
| `standard` | Regular product without variations | ✅ Yes | ❌ No |
| `parent` | Template with variation definitions | ❌ No | ✅ Yes |
| `child` | Specific variant of a parent | ✅ Yes | ❌ No (inherits from parent) |
| `bundle` | Bundle with component products | ✅ Yes* | ❌ No |

*Bundles require configuration - see [Bundle Products Guide](../bundles/overview)

## Routing Based on Product Type

Here's a complete implementation pattern that handles all product types:

```typescript
async function ProductPage({ productId }) {
  // Fetch product with all necessary includes
  const response = await getByContextProduct({
    path: { product_id: productId },
    query: { 
      include: ['main_image', 'files', 'component_products'] 
    }
  });

  const productData = response.data?.data;
  if (!productData) return <NotFound />;

  // Route based on product type
  switch (productData.meta?.product_types?.[0]) {
    case 'standard':
      return <DisplayStandardProduct productData={response.data} />;
      
    case 'parent':
      // Parent product already has variation data
      return <DisplayVariationProduct productData={response.data} />;
      
    case 'child':
      // Child variant needs parent for full variation context
      const parentResponse = await getByContextProduct({
        path: { product_id: productData.attributes?.base_product_id! },
        query: { include: ['main_image', 'files'] }
      });
      
      return <DisplayVariationProduct 
        productData={response.data}
        parentProduct={parentResponse.data} 
      />;
      
    case 'bundle':
      return <DisplayBundleProduct productData={response.data} />;
      
    default:
      // Fallback to standard display
      return <DisplayStandardProduct productData={response.data} />;
  }
}
```

### Key Implementation Notes

1. **Use the same component for parent and child** - They share the same display logic
2. **Child products need parent context** - Always fetch the parent for variation options
3. **Include necessary data upfront** - Reduces additional API calls
4. **Handle loading and error states** - Better user experience

## Key Relationships

### Child → Parent Relationship

Child products reference their parent:

```typescript
// Child product structure
{
  id: "child-uuid",
  attributes: {
    base_product_id: "parent-uuid",  // Points to parent
    // ... other attributes
  },
  meta: {
    product_types: ["child"]
  }
}
```

### Parent → Children Relationship

Parent products contain variation data:

```typescript
// Parent product structure
{
  id: "parent-uuid",
  meta: {
    product_types: ["parent"],
    variations: [...],          // Variation definitions
    variation_matrix: {...}     // Maps options to child IDs
  }
}
```

## When to Fetch Additional Data

### For Child Products

When you detect a child product, you typically need the parent for:
- Variation options to display
- Pre-selecting current variant
- Enabling variant switching

```typescript
if (productType === 'child') {
  const parentId = product.attributes?.base_product_id;
  if (parentId) {
    // Fetch parent - see "List Parent & Child Products" guide
    const parentData = await getByContextProduct({
      path: { product_id: parentId }
    });
  }
}
```

### For Parent Products

Parent products already contain variation data:
- `meta.variations` - Option definitions
- `meta.variation_matrix` - Child product mapping

You may want to fetch child products for:
- Displaying all variants in a table
- Showing price ranges
- Getting variant-specific data (SKUs, prices)

## Key Points to Remember

- **Only child and standard products** can be added to cart
- **Child products** always have `base_product_id`
- **Parent products** contain all variation definitions
- **Product type** determines your UI/UX approach

## Next Steps

Now that you can detect product types:

- **For parent/child products**: Continue to [List Parent & Child Products](./list-parent-child.mdx)
- **For implementation patterns**: See [Variation Selection Patterns](./variation-selection-patterns.mdx)

## References

- [Product Types Guide](/docs/commerce-manager/product-experience-manager/products/overview#product-types)
- [Get Product API](/docs/api/pxm/catalog/get-by-context-product)

---

## List Parent & Child Products

Learn which SDK calls to use for fetching variation data and what options are available.

:::info Authentication Required
You'll need to set up authentication with the Shopper SDK. See the [Authentication Quick Start](/docs/developer-tools/fundamentals/authentication/quickstart) guide.
:::

## SDK Functions for Variations

### getByContextProduct

Fetches a single product (parent, child, or standard).

```typescript
import { getByContextProduct } from '@epcc-sdk/sdks-shopper';

const response = await getByContextProduct({
  path: { 
    product_id: 'PRODUCT_ID' 
  },
  query: {
    include: ['main_image', 'files']
  }
});
```

**Key points:**
- Works for any product type (parent, child, standard)
- Parent products contain `meta.variations` and `meta.variation_matrix`
- Child products contain `attributes.base_product_id` pointing to parent
- Use `include` to fetch related data in a single request

**Available includes:**
- `main_image` - Primary product image
- `files` - All product files/images
- `categories` - Product categories
- `brands` - Product brand

### getByContextChildProducts

Fetches all child products for a given parent.

```typescript
import { getByContextChildProducts } from '@epcc-sdk/sdks-shopper';

const response = await getByContextChildProducts({
  path: { 
    product_id: 'PARENT_ID' 
  },
  query: {
    page: {
      limit: 100,  // Max 100 per page
      offset: 0
    },
    filter: {}   // Optional filters
  }
});
```

**Key points:**
- Only works with parent product IDs
- Returns array of child products
- Supports pagination for parents with many variants
- Each child contains full product data (price, inventory, SKU)

**Common use cases:**
- Building a variations table showing all options
- Checking inventory across all variants
- Displaying price ranges
- Preloading all variant data for quick switching

## Common Patterns

### Pattern 1: Display Parent with All Variants

```typescript
// Fetch parent product with variation data
const parentResponse = await getByContextProduct({
  path: { product_id: parentId },
  query: { include: ['main_image'] }
});

// If you need full child data (prices, inventory, etc.)
const childrenResponse = await getByContextChildProducts({
  path: { product_id: parentId }
});
```

**When to use:**
- Product detail pages showing all variations
- Building variation tables with prices/inventory
- Displaying all available options

### Pattern 2: Landing on a Child Product

```typescript
// 1. Fetch the child product
const childResponse = await getByContextProduct({
  path: { product_id: childId },
  query: { include: ['main_image'] }
});

// 2. Get parent ID from child
const parentId = childResponse.data?.data?.attributes?.base_product_id;

// 3. Fetch parent for variation context
const parentResponse = await getByContextProduct({
  path: { product_id: parentId }
});
```

**When to use:**
- Direct links to specific variants
- Search results landing on child products
- Pre-selecting current variant options

### Pattern 3: Inventory Management

Inventory is managed separately from product data in Elastic Path. To check stock levels:

```typescript
import { getStock } from '@epcc-sdk/sdks-shopper';

// Fetch inventory for a specific product
const stockResponse = await getStock({
  path: { product_uuid: productId }
});

// Stock data includes available, allocated, and total
const stock = stockResponse.data?.data?.attributes;
```

**When to use:**
- Checking stock levels before allowing add to cart
- Displaying availability indicators
- Filtering out-of-stock variants

**Note:** For multi-location inventory, see the [Inventory API documentation](/docs/api/pxm/inventory/inventory)

## Response Data Structure

### Parent Product Response
```typescript
{
  data: {
    id: "parent-uuid",
    type: "product",
    attributes: {
      name: "T-Shirt",
      sku: "TS-PARENT"
    },
    meta: {
      product_types: ["parent"],
      variations: [
        {
          id: "size-variation-id",
          name: "Size",
          options: [
            { id: "small-id", name: "Small" },
            { id: "medium-id", name: "Medium" }
          ]
        }
      ],
      variation_matrix: {
        "color-option-id": {
          "size-option-id": "child-product-id"
        }
      }
    }
  }
}
```

### Child Products Response
```typescript
{
  data: [
    {
      id: "child-uuid",
      type: "product",
      attributes: {
        name: "T-Shirt",
        sku: "TS-S-BL",
        base_product_id: "parent-uuid",
        price: {
          USD: { amount: 2999, includes_tax: false }
        },
        // Note: inventory is managed separately via inventory API
      },
      meta: {
        product_types: ["child"]
      }
    }
    // ... more children
  ]
}
```

## Performance Tips

- **Use includes wisely** - Fetch related data in one request when possible
- **Cache parent data** - Variation structure rarely changes
- **Paginate large sets** - Use pagination for products with 50+ variants
- **Selective fetching** - Only fetch child products when you need their specific data

## Next Steps

With variation data loaded:

- **To implement selection**: Continue to [Select a Variation](./select-variation.mdx)
- **To understand the matrix**: See [Understanding the Variation Matrix](./variation-matrix-guide.mdx)
- **For complete examples**: View the [Composable Frontend implementation](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)

## References

- [Get Child Products API](/docs/api/pxm/catalog/get-by-context-child-products)
- [Product Relationships](/docs/api/pxm/products/get-product-variation-relationships)
- [Composable Frontend Examples](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)

---

## Variations Overview

Product variations allow you to offer multiple versions of a product based on attributes like size, color, or material. Elastic Path uses a parent/child model where variant products (children) are automatically generated from attribute combinations.

## Common Use Cases

Variations are ideal for products that share core characteristics but differ in specific attributes:

- **Apparel**: T-shirts in different sizes (S, M, L) and colors
- **Electronics**: Phones with different storage capacities (128GB, 256GB, 512GB) and colors
- **Furniture**: Chairs in different finishes (oak, walnut, cherry) and sizes
- **Software**: Licenses with different durations (monthly, annual) and user limits
- **Consumables**: Products in different quantities or packaging sizes

## When to Use Variations

### Use Variations When:
- Products share the same base description and features
- Differences are limited to specific attributes (size, color, material)
- You want shoppers to select options from a single product page
- Inventory needs to be tracked per variant

### Don't Use Variations When:
- Products have fundamentally different features or specifications
- Products belong to different categories
- The products don't share a common base (e.g., a laptop vs a mouse)
- Each variant needs completely different product information architecture

## Key Benefits

Using variations provides several advantages over creating separate products:

- **Automatic SKU Generation**: Child products are created automatically from option combinations
- **Simplified Management**: Update shared attributes once on the parent product
- **Better Shopper Experience**: Customers can easily compare and select options on a single page
- **Inventory Tracking**: Each variant maintains its own stock levels independently
- **Consistent Pricing**: Apply pricing rules across all variants or set individual prices

## Parent vs Child Products

### Parent-Child Relationship

```mermaid
graph TD
    P[Parent ProductT-Shirt Base Template] --> |Generates| VM[Variation Matrix]
    VM --> C1[Child 1Small/BlueSKU: TS-S-BL]
    VM --> C2[Child 2Small/RedSKU: TS-S-RD]
    VM --> C3[Child 3Medium/BlueSKU: TS-M-BL]
    VM --> C4[Child 4Medium/RedSKU: TS-M-RD]
    VM --> C5[... more variants]
    
    classDef parent fill:#E1F5FE,stroke:#0288D1,color:#000
    classDef matrix fill:#FFF3E0,stroke:#F57C00,color:#000
    classDef child fill:#E8F5E9,stroke:#4CAF50,color:#000
    
    class P parent
    class VM matrix
    class C1,C2,C3,C4,C5 child
```

### Parent Product
The parent product serves as a template that:
- Defines the base product information
- Contains variation options (size, color, etc.)
- Is not directly purchasable
- Generates child products based on attribute combinations

### Child Products (Variants)
Child products are the actual purchasable SKUs that:
- Inherit attributes from the parent
- Have unique combinations of variation options
- Contain specific pricing and inventory
- Are what shoppers add to cart

### What Frontend Developers Need to Know

When building variation selection in your storefront, keep these critical points in mind (for implementation details, see [Handling Product Types](./handling-product-types.mdx)):

#### Child Product IDs Change
- Child product IDs are regenerated when the catalog is republished
- This impacts saved carts, wishlists, and bookmarked URLs
- Always fetch fresh child data using the parent's variation matrix

#### Cart Operations
- **Never** attempt to add a parent product to cart - it will fail
- Always use the child product ID for cart operations (see [Select a Variation](./select-variation.mdx))
- Each child maintains its own inventory level

#### Data Fetching Strategy
- When on a parent product: Use its own variation data
- When on a child product: Fetch the parent for variation context (see [List Parent & Child Products](./list-parent-child.mdx))
- Variation structure rarely changes (good candidate for caching)

#### Matrix Structure Varies
- The variation matrix structure differs between products
- Don't hardcode assumptions about which variation is at which level
- Use the recursive lookup pattern for flexibility (see [Understanding the Variation Matrix](./variation-matrix-guide.mdx))

## Variation Options & Attributes

Variations are built using:
- **Options**: The variation types (e.g., "Size", "Color")
- **Option Values**: Specific choices (e.g., "Small", "Medium", "Large")
- **Variation Matrix**: All possible combinations of option values

Example: A t-shirt with 3 sizes and 4 colors generates 12 child products.

### How Options Create Variants

When you define variations on a parent product, Elastic Path automatically generates all valid combinations as child products:

```mermaid
graph TB
    subgraph "Variation Options"
        direction LR
        Size[Size:Small, Medium, Large]
        Color[Color:Blue, Red, Green, Black]
    end
    
    Size & Color --> Matrix[Variation Matrix3 sizes × 4 colors]
    
    Matrix --> Variants[12 Child ProductsCreated Automatically]
    
    subgraph "Examples (3 of 12 variants)"
        V1[Small/Blue - SKU: TS-S-BL]
        V2[Medium/Red - SKU: TS-M-RD]
        V3[Large/Green - SKU: TS-L-GN]
        More[... and 9 more variants]
    end
    
    Variants -.-> V1 & V2 & V3 & More
    
    classDef option fill:#E3F2FD,stroke:#1976D2,color:#000
    classDef matrix fill:#FFF3E0,stroke:#F57C00,color:#000
    classDef result fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef more fill:#F5F5F5,stroke:#9E9E9E,color:#000,stroke-dasharray: 5 5
    
    class Size,Color option
    class Matrix matrix
    class Variants,V1,V2,V3 result
    class More more
```

#### Real-World Example

Here's how variation data looks in practice:

```typescript
// Parent product variation structure
const parentProduct = {
  id: "a2c20cd6-5f34-47b6-9582-5044a5b50991",
  attributes: {
    name: "Classic T-Shirt",
    sku: "TS-PARENT" // Parent SKU
  },
  meta: {
    product_types: ["parent"],
    variations: [
      {
        id: "10a35688-d48e-4228-8bd2-b3b5f71c992d",
        name: "Size",
        options: [
          { id: "8f749ee2-17fb-4876-963f-2f57c0dffd97", name: "Small" },
          { id: "d536955b-afa3-40e4-88cc-f6ee0248eeea", name: "Medium" },
          { id: "bbd91e51-690b-4743-9eb7-185a5bb88a62", name: "Large" }
        ]
      },
      {
        id: "6cc91048-c351-4b35-aacd-8d613d515fa7",
        name: "Color", 
        options: [
          { id: "801eabad-5108-4991-9f98-1830252214eb", name: "Blue" },
          { id: "84fd8ba0-9829-4b79-bfe9-ffee1ab60b95", name: "Red" }
        ]
      }
    ]
  }
}

// Resulting child product example
const childProduct = {
  id: "ed971d72-ca0c-4472-86f9-db03227bebfd",
  attributes: {
    name: "Classic T-Shirt", // Inherits from parent
    sku: "TS-S-BL", // Unique SKU for Small/Blue
    price: [{ amount: 2499, currency: "USD" }]
    // Note: inventory is managed via separate inventory API
  },
  meta: {
    product_types: ["child"],
    base_product_id: "a2c20cd6-5f34-47b6-9582-5044a5b50991" // Parent reference
  }
}
```

:::info Excluding Invalid Combinations
The variation matrix automatically creates all valid combinations. You can exclude specific combinations using [variation modifiers](/docs/api/pxm/products/variations#create-variation-modifiers).

For example, if "Extra Small" size isn't available in "Black" color, you can create a modifier to exclude that specific combination from being generated.
:::

## Common Implementation Patterns

Choose the right variation selection pattern based on your storefront needs:

| Pattern | Best For | SEO | Performance | Complexity | Mobile UX |
|---------|----------|-----|-------------|------------|-----------|
| **Navigation-Based** | Traditional sites, SEO-critical | ✅ Excellent | ⚡ Slower | 🟢 Simple | ⭐⭐⭐ |
| **Dynamic State** | SPAs, mobile apps | ❌ Limited | ⚡⚡⚡ Fast | 🟡 Moderate | ⭐⭐⭐⭐ |
| **Hybrid** | Modern storefronts | ✅ Good | ⚡⚡ Fast | 🔴 Complex | ⭐⭐⭐⭐ |
| **Quick Shop** | Product listings | ❌ None | ⚡⚡⚡ Fast | 🟢 Simple | ⭐⭐⭐⭐⭐ |

For detailed implementation examples and code for each pattern, see [Variation Selection Patterns](./variation-selection-patterns.mdx).

## Understanding the Variation Matrix

The variation matrix is a nested data structure that maps option combinations to child product IDs. Key points:

- **Uses option IDs as keys** (not variation IDs)
- **Nesting depth = number of variations** (2 variations = 2 levels deep)
- **Order is unpredictable** - use recursive lookup
- **Leaf values are child product IDs**

Example structure:
```json
{
  "color_option_id": {
    "size_option_id": "child_product_id"
  }
}
```

For implementation details, including the recursive lookup function and complete examples, see [Understanding the Variation Matrix](./variation-matrix-guide.mdx).

## Key Data Structures

### Product Types
Every product has a type in `meta.product_types[0]`:
```typescript
// Check product type
const productType = product.data?.meta?.product_types?.[0]
// Values: "parent", "child", "standard"
```

### Variation Options
Available on parent products in `meta.variations`:
```typescript
// Example variations structure
[
  {
    "id": "size_variation",
    "name": "Size",
    "options": [
      { "id": "small", "name": "Small" },
      { "id": "medium", "name": "Medium" }
    ]
  }
]
```

## Frontend Implementation Considerations

When building variation selection in your storefront, consider these key areas:

### User Experience

#### Loading States
```typescript
// Show loading state during variant switches
const [isLoadingVariant, setIsLoadingVariant] = useState(false);

async function handleVariantChange(childId: string) {
  setIsLoadingVariant(true);
  try {
    const childData = await fetchProduct(childId);
    updateDisplay(childData);
  } finally {
    setIsLoadingVariant(false);
  }
}
```

#### Unavailable Combinations
```typescript
// Disable unavailable option combinations
function isOptionAvailable(optionId: string, selectedOptions: Record<string, string>) {
  const testOptions = { ...selectedOptions, [currentVariationId]: optionId };
  const childId = getSkuIdFromOptions(Object.values(testOptions), variationMatrix);
  
  if (!childId) return false;
  
  // Optional: Check inventory via separate API call
  // See inventory API documentation for stock checking
}
```

#### Mobile Considerations
- Use native select dropdowns for better mobile UX
- Consider sticky add-to-cart buttons
- Minimize scrolling between option selection and cart button

### Data Fetching Tips

1. **For Parent Products**: Use variation data directly from parent
2. **For Child Products**: Always fetch parent for full context
3. **Batch Operations**: Fetch all children in one request when possible

## Common Frontend Pitfalls

Avoid these common mistakes when implementing variations:

### 1. Not Checking Product Type
```typescript
// ❌ Wrong: Assuming all products have variations
const variations = product.meta.variations; // May be undefined

// ✅ Correct: Check product type first
const productType = product.meta?.product_types?.[0];
if (productType === 'parent') {
  const variations = product.meta.variations;
}
```

### 2. Trying to Add Parent to Cart
```typescript
// ❌ Wrong: Adding parent product ID
addToCart(parentProduct.id); // Will fail!

// ✅ Correct: Only add child product IDs
const childId = getSkuIdFromOptions(selectedOptions, variationMatrix);
if (childId) {
  addToCart(childId);
}
```

### 3. Hardcoding Matrix Structure
```typescript
// ❌ Wrong: Assuming color is always first level
const childId = matrix[colorId][sizeId]; // May fail!

// ✅ Correct: Use recursive lookup
const childId = getSkuIdFromOptions([colorId, sizeId], matrix);
```

### 4. Not Pre-selecting on Child Products
```typescript
// ❌ Wrong: Showing empty selections on child product page
// User loses context of what variant they're viewing

// ✅ Correct: Pre-select current variant's options
if (productType === 'child') {
  const parent = await fetchParent(product.attributes.base_product_id);
  const currentSelections = getCurrentSelections(product.id, parent.meta.variation_matrix);
  setSelectedOptions(currentSelections);
}
```

See [List Parent & Child Products](./list-parent-child.mdx) for a complete example of pre-selecting options.

### 5. Ignoring Loading States
```typescript
// ❌ Wrong: No feedback during variant switches
handleOptionSelect(optionId); // User doesn't know something is happening

// ✅ Correct: Show loading state
setIsLoading(true);
await handleOptionSelect(optionId);
setIsLoading(false);
```

### 6. Forgetting Mobile UX
```typescript
// ❌ Wrong: Tiny color swatches on mobile

  {colors.map(color => <ColorSwatch size="xs" />)}

// ✅ Correct: Mobile-friendly selection
<select onChange={handleColorSelect}>
  {colors.map(color => <option value={color.id}>{color.name}</option>)}
</select>
```

For more UI patterns, see [Variation Selection Patterns](./variation-selection-patterns.mdx).

### 7. Not Handling Invalid Combinations
```typescript
// ❌ Wrong: Allowing selection of unavailable combinations
// User gets error when trying to add to cart

// ✅ Correct: Validate combinations exist
const isValidCombination = getSkuIdFromOptions(selectedOptions, matrix) !== undefined;
setAddToCartEnabled(isValidCombination);
```

## Troubleshooting

### Common Issues and Solutions

#### "404 Not Found" when accessing child products
- **Cause**: Child product IDs change when catalog is republished
- **Solution**: Always fetch fresh child data using `getByContextChildProducts`

#### Empty variation_matrix on parent product
- **Cause**: Catalog not published or variations not properly configured
- **Solution**: Ensure catalog is published and variations have been built

#### "base_product_id" is missing on child product
- **Cause**: Product is not actually a child variant
- **Solution**: Check `meta.product_types[0]` equals "child"

#### Can't add parent product to cart
- **Cause**: Parent products are templates, not purchasable items
- **Solution**: Always add the specific child product ID to cart

#### Variation options not showing correctly
- **Cause**: Incorrect option order when using variation_matrix
- **Solution**: Use the same order as the variations array from parent

#### Inventory not showing on product
- **Cause**: Inventory is managed separately via the inventory API
- **Solution**: Use the `getStock` function from the SDK to fetch inventory data

## Learning Path

Follow this recommended path to master variation implementation:

1. **[Handling Product Types](./handling-product-types.mdx)**  
   Learn to detect and handle different product types (parent, child, standard)
   
2. **[List Parent & Child Products](./list-parent-child.mdx)**  
   Fetch and display parent products with their child variants
   
3. **[Select a Variation](./select-variation.mdx)**  
   Implement variation selection and add variants to cart
   
4. **[Understanding the Variation Matrix](./variation-matrix-guide.mdx)** *(Advanced)*  
   Deep dive into the variation matrix structure and recursive lookup
   
5. **[Variation Selection Patterns](./variation-selection-patterns.mdx)**  
   Choose and implement the best UI pattern for your storefront

## Next Steps

### How-To Guides
- [Handling Product Types](./handling-product-types.mdx) - Detect and handle different product types
- [Variation Selection Patterns](./variation-selection-patterns.mdx) - Different UI/UX approaches
- [List Parent & Child Products](./list-parent-child.mdx) - Work with parent-child relationships
- [Select a Variation](./select-variation.mdx) - Implement variation selection

### Related Topics
- [Bundle Products](../bundles/overview)
- [Cart Management](/docs/developer-tools/fundamentals/cart/overview)
- [Inventory Management](/docs/api/pxm/inventory/inventory)

## References

- [Variations API Guide](/docs/api/pxm/products/variations)
- [Product Variations in Commerce Manager](/docs/commerce-manager/product-experience-manager/variations)
- [Composable Frontend Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)

---

## Select a Variation

Learn how to validate variation selections, resolve the correct child product using the variation matrix, and add it to cart with proper error handling.

### Selection Flow

```mermaid
flowchart TD
    A[User views parent product] --> B[Fetch all child variants]
    B --> C[Display option selectors]
    C --> D{User selects options}
    D --> |Size: MediumColor: Blue| E[Filter variants by selection]
    E --> F[Find matching child product]
    F --> G{Match found?}
    G -->|Yes| H[Enable Add to Cart]
    G -->|No| I[Show unavailable message]
    H --> J[Add child product ID to cart]
    
    classDef start fill:#E3F2FD,stroke:#1976D2,color:#000
    classDef process fill:#FFF9C4,stroke:#F9A825,color:#000
    classDef success fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef error fill:#FFCDD2,stroke:#D32F2F,color:#000
    
    class A start
    class B,C,E,F process
    class D,G process
    class H,J success
    class I error
```

### 1. Validate All Options Selected

Before resolving a child product, ensure all variations have selections:

```typescript
function validateSelections(
  selectedOptions: Record<string, string>,
  variations: Variation[]
): { isValid: boolean; missing: string[] } {
  const missing = variations
    .filter(v => !selectedOptions[v.id])
    .map(v => v.name);
    
  return {
    isValid: missing.length === 0,
    missing
  };
}

// Example usage
const validation = validateSelections(selectedOptions, variations);
if (!validation.isValid) {
  return { error: `Please select: ${validation.missing.join(', ')}` };
}
```

### 2. Resolve Child Product

Use the variation matrix to find the child product ID:

```typescript
import { getSkuIdFromOptions } from '@/utils/product-helper';

// Collect selected option IDs in order
const optionIds = Object.values(selectedOptions);

// Look up child product ID
const childId = getSkuIdFromOptions(optionIds, variationMatrix);

if (!childId) {
  return { error: 'This combination is not available' };
}
```

:::info
See [Understanding the Variation Matrix](./variation-matrix-guide.mdx) for the `getSkuIdFromOptions` implementation.
:::

### 3. Add to Cart

Add the resolved child product to cart using the SDK:

```typescript
import { manageCarts, getCartId } from '@epcc-sdk/sdks-shopper';

const cartId = getCartId();

await manageCarts({
  path: { cartID: cartId },
  body: { 
    data: { 
      type: 'cart_item',
      id: childId,  // Must be child product ID, not parent!
      quantity: 1
    }
  }
});
```

## Key Points

- **Validate first** - Check all options are selected before lookup
- **Child ID only** - Never attempt to add parent product to cart
- **Handle errors** - Invalid combinations and out of stock scenarios
- **Loading states** - Show feedback during async operations
- **Inventory checks** - Optional but recommended for better UX

## Next Steps

With selection implemented:

- **Choose a UI pattern**: See [Variation Selection Patterns](./variation-selection-patterns.mdx)
- **Manage the cart**: Continue to [Cart Management](/docs/developer-tools/fundamentals/cart/overview)

## References

- [Add Items to Cart Guide](/docs/api/carts/manage-carts#add-product-to-cart)
- [Cart Management API](/docs/api/carts/manage-carts)

---

## Understanding the Variation Matrix

Learn how to work with Elastic Path's variation matrix, a powerful nested structure that maps product options to child product IDs. Master the matrix structure and implement robust product selection logic that handles any number of variations.

## Understanding the Structure

The variation matrix uses option IDs (not variation IDs) as keys. The structure depth depends on how many variations your product has:

```mermaid
graph TB
    subgraph "User Selection"
        U[User selects: Black leather, Small size]
    end
    
    subgraph "2-Level Matrix Structure"
        M1["matrix['black_option_id']['small_option_id']↓Returns: 'child_product_id'"]
    end
    
    subgraph "Real Example"
        E1["First level: Color options(Black, Brown, Chestnut)"]
        E2["Second level: Size options(Small, Medium, Large, XL)"]
        E3["Value: Child product UUID"]
    end
    
    U --> M1
    M1 --> E1
    E1 --> E2
    E2 --> E3
    
    classDef user fill:#E3F2FD,stroke:#1976D2,color:#000
    classDef structure fill:#FFF3E0,stroke:#F57C00,color:#000
    classDef example fill:#F5F5F5,stroke:#757575,color:#000
    
    class U user
    class M1 structure
    class E1,E2,E3 example
```

Here's a real variation matrix structure:

```json
{
  "801eabad-5108-4991-9f98-1830252214eb": {  // Black leather option ID
    "8f749ee2-17fb-4876-963f-2f57c0dffd97": "ed971d72-ca0c-4472-86f9-db03227bebfd",  // Small
    "d536955b-afa3-40e4-88cc-f6ee0248eeea": "ca9791a6-5adb-4207-8ea3-5a5b3d58fc4f",  // Medium
    "bbd91e51-690b-4743-9eb7-185a5bb88a62": "86ffccbe-6dfa-4903-9861-27eaef046761",  // Large
    "a987256b-76d1-4dad-b59e-fcc1c6198d1f": "9df52c2e-a145-4ee5-9abe-2d2961fadd2d"   // XL
  },
  "84fd8ba0-9829-4b79-bfe9-ffee1ab60b95": {  // Chestnut leather option ID
    "8f749ee2-17fb-4876-963f-2f57c0dffd97": "7ed766a9-7e1c-4fce-bfed-0455bf4c3af0",  // Small
    // ... more size options
  }
  // ... more color options
}
```

## Key Concepts

1. **Option IDs as Keys**: The matrix uses option IDs directly, not variation IDs
2. **Nesting Order**: Determined by how variations were configured (often alphabetical or creation order)
3. **Flexible Depth**: 2 levels for 2 variations, 3 levels for 3 variations, etc.
4. **No Fixed Pattern**: The first level could be Size or Color depending on your product setup

## Implementation Approach: Recursive Lookup

The most flexible approach is to use a recursive function that can handle any depth of nesting:

```typescript
// Recursive function used by Elastic Path's Composable Frontend
export function getSkuIdFromOptions(
  options: string[],
  matrix: any
): string | undefined {
  // Base case: if we've reached a child product ID (string)
  if (typeof matrix === 'string') {
    return matrix;
  }

  // Try each option as a key in the current matrix level
  for (const currOption in options) {
    const optionId = options[currOption];
    const nestedMatrix = matrix[optionId];
    
    if (nestedMatrix) {
      // Recurse deeper into the matrix
      return getSkuIdFromOptions(options, nestedMatrix);
    }
  }

  return undefined;
}

// Usage example
const selectedOptions = [
  '801eabad-5108-4991-9f98-1830252214eb',  // Black leather
  '8f749ee2-17fb-4876-963f-2f57c0dffd97'   // Small size
];

const childProductId = getSkuIdFromOptions(selectedOptions, variationMatrix);
// Returns: 'ed971d72-ca0c-4472-86f9-db03227bebfd'
```

## Why Use Recursive Lookup?

1. **Handles Any Number of Variations**: Works with 1, 2, 3+ variations without modification
2. **Order Agnostic**: Doesn't need to know which variation is at which level
3. **Future Proof**: Adapts to changes in how variations are structured
4. **Production Tested**: Used in Elastic Path's official example implementation

## Alternative: Direct Lookup (When You Know the Structure)

If you know your matrix structure is always consistent (e.g., Color → Size), you can use direct lookup:

```typescript
// Direct lookup when you know the structure
function getChildDirectly(
  colorOptionId: string,
  sizeOptionId: string,
  matrix: any
): string | undefined {
  return matrix[colorOptionId]?.[sizeOptionId];
}

// Much simpler, but less flexible
const childId = getChildDirectly(
  '801eabad-5108-4991-9f98-1830252214eb',  // Black
  '8f749ee2-17fb-4876-963f-2f57c0dffd97',  // Small
  variationMatrix
);
```

## Complete Example: From Selection to Cart

Here's a full implementation showing how to use the recursive lookup:

```typescript
import { getSkuIdFromOptions } from '@/utils/product-helper';

// Parent product with variations
const parentProduct = {
  id: "a2c20cd6-5f34-47b6-9582-5044a5b50991",
  meta: {
    variations: [
      { 
        id: "10a35688-d48e-4228-8bd2-b3b5f71c992d", 
        name: "Couch Size",
        options: [
          { id: "8f749ee2-17fb-4876-963f-2f57c0dffd97", name: "Small" },
          { id: "d536955b-afa3-40e4-88cc-f6ee0248eeea", name: "Medium" }
        ]
      },
      { 
        id: "6cc91048-c351-4b35-aacd-8d613d515fa7", 
        name: "Leather Color",
        options: [
          { id: "801eabad-5108-4991-9f98-1830252214eb", name: "Black" },
          { id: "84fd8ba0-9829-4b79-bfe9-ffee1ab60b95", name: "Chestnut" }
        ]
      }
    ],
    variation_matrix: {
      "801eabad-5108-4991-9f98-1830252214eb": {  // Black
        "8f749ee2-17fb-4876-963f-2f57c0dffd97": "ed971d72-ca0c-4472-86f9-db03227bebfd",  // Small
        "d536955b-afa3-40e4-88cc-f6ee0248eeea": "ca9791a6-5adb-4207-8ea3-5a5b3d58fc4f"   // Medium
      },
      "84fd8ba0-9829-4b79-bfe9-ffee1ab60b95": {  // Chestnut
        "8f749ee2-17fb-4876-963f-2f57c0dffd97": "7ed766a9-7e1c-4fce-bfed-0455bf4c3af0",  // Small
        "d536955b-afa3-40e4-88cc-f6ee0248eeea": "1478ea17-078c-4e3c-b3b0-d8400823a3ba"   // Medium
      }
    }
  }
};

// Component implementation
function VariationSelector({ parentProduct, onAddToCart }) {
  const [selectedOptions, setSelectedOptions] = useState({});
  
  const handleOptionSelect = (variationId: string, optionId: string) => {
    setSelectedOptions(prev => ({
      ...prev,
      [variationId]: optionId
    }));
  };
  
  const handleAddToCart = () => {
    // Get selected option IDs as an array
    const optionIds = Object.values(selectedOptions);
    
    // Use recursive lookup
    const childId = getSkuIdFromOptions(
      optionIds,
      parentProduct.meta.variation_matrix
    );
    
    if (childId) {
      onAddToCart(childId);
    }
  };
  
  // Check if all variations have selections
  const allSelected = parentProduct.meta.variations.every(
    v => selectedOptions[v.id] !== undefined
  );
  
  return (
    
      {/* Render variation options */}
      {parentProduct.meta.variations.map(variation => (
        <VariationOptions
          key={variation.id}
          variation={variation}
          selectedId={selectedOptions[variation.id]}
          onSelect={(optionId) => handleOptionSelect(variation.id, optionId)}
        />
      ))}
      
      <button 
        disabled={!allSelected}
        onClick={handleAddToCart}
      >
        Add to Cart
      </button>
    
  );
}
```

## Key Takeaways

### Understanding the Variation Matrix

1. **Structure**: The matrix uses option IDs as keys, not variation IDs
2. **Nesting Order**: Determined by product configuration, not predictable
3. **Depth**: Equals the number of variations (2 variations = 2 levels deep)
4. **Values**: The leaf nodes are always child product UUIDs

### Best Practices

1. **Use Recursive Lookup**: The `getSkuIdFromOptions` function handles any variation structure
2. **Don't Assume Order**: The matrix structure can vary between products
3. **Validate Selections**: Ensure all variations have selections before lookup
4. **Handle Edge Cases**: Check for undefined results and provide user feedback

### Common Pitfalls to Avoid

1. **Don't hardcode matrix structure** - It varies by product
2. **Don't assume which variation is at which level** - Use recursive lookup
3. **Don't forget to handle products with 1 or 3+ variations**
4. **Don't mix up variation IDs with option IDs** - The matrix uses option IDs

## Next Steps

- [Variation Selection Patterns](./variation-selection-patterns.mdx) - Different UI patterns for implementing variation selection
- [Select a Variation](./select-variation.mdx) - Step-by-step guide to building a variation selector

## References

- [Composable Frontend Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)
- [Catalog API Reference](/docs/api/pxm/catalog)

---

## Variation Selection Patterns

Explore different patterns for implementing variation selection, each with its own benefits for different use cases. Understand and implement the best variation selection pattern for your storefront's user experience needs.

## Quick Start

Choose the right variation selection pattern for your storefront:

```mermaid
flowchart TD
    A[Start] --> B{Need SEO-friendly URLs?}
    B -->|Yes| C{Single-page app?}
    B -->|No| D{Quick selection needed?}
    C -->|Yes| E[Pattern 3: Hybrid]
    C -->|No| F[Pattern 1: Navigation]
    D -->|Yes| G[Pattern 4: Quick Shop]
    D -->|No| H[Pattern 2: Dynamic State]
    
    style E fill:#C8E6C9,stroke:#388E3C,color:#000
    style F fill:#C8E6C9,stroke:#388E3C,color:#000
    style G fill:#C8E6C9,stroke:#388E3C,color:#000
    style H fill:#C8E6C9,stroke:#388E3C,color:#000
```

### Pattern Overview

1. **[Navigation-Based](#pattern-1-navigation-based-selection)** - Traditional approach with page reloads
2. **[Dynamic State](#pattern-2-dynamic-state-management)** - Modern SPA approach with fast updates
3. **[Hybrid](#pattern-3-hybrid-approach)** - Best of both worlds
4. **[Quick Shop Modal](#pattern-4-quick-shop-modal)** - For product listings

## Choosing the Right Pattern

| Pattern | Best For | SEO | Performance | Complexity |
|---------|----------|-----|-------------|------------|
| **Navigation-Based** | Traditional storefronts, SEO-critical sites | ✅ Excellent | ⚡ Slower | 🟢 Simple |
| **Dynamic State** | SPAs, mobile apps | ❌ Limited | ⚡⚡⚡ Fast | 🟡 Moderate |
| **Hybrid** | Modern storefronts wanting both | ✅ Good | ⚡⚡ Fast | 🔴 Complex |
| **Quick Shop Modal** | Product listings, quick add | ❌ None | ⚡⚡⚡ Fast | 🟢 Simple |

## Pattern 1: Navigation-Based Selection

### Overview

Navigate to child product URLs as options are selected. This traditional approach reloads the page for each selection, making it ideal for SEO-critical sites and traditional storefronts.

### When to Use

- SEO is critical for your business
- You need direct URLs to each variant
- Browser history navigation is important
- You're building a traditional e-commerce site

### Key Characteristic

When all options are selected, navigate to the child product URL:

```mermaid
flowchart LR
    A[User selects option] --> B[Find child ID in matrix]
    B --> C[Navigate to /products/childId]
    C --> D[Page loads child product]
    
    style A fill:#E3F2FD,stroke:#1976D2,color:#000
    style D fill:#C8E6C9,stroke:#388E3C,color:#000
```

### Implementation Focus

```typescript
const router = useRouter();

const handleOptionSelect = (variationId: string, optionId: string) => {
  const newOptions = {
    ...selectedOptions,
    [variationId]: optionId
  };
  
  // Key difference: Navigate on selection
  const childId = getSkuIdFromOptions(
    Object.values(newOptions),
    variationMatrix
  );
  
  if (childId && allOptionsSelected(newOptions)) {
    router.replace(`/products/${childId}`);
  }
};
```

### Pros & Cons

✅ **SEO-friendly URLs** - Each variant has its own URL  
✅ **Direct links** - Share specific variant URLs  
✅ **Browser navigation** - Back/forward works naturally  
✅ **Simple implementation** - Easy to understand and maintain  
❌ **Page refresh** - Full reload on each selection  
❌ **Slower experience** - Perceived performance is slower  

## Pattern 2: Dynamic State Management

### Overview

Keep the parent URL and update the display dynamically based on selections. This modern approach provides instant feedback without page reloads, perfect for single-page applications and mobile apps.

### When to Use

- Building a single-page application (SPA)
- Performance and user experience are priorities
- SEO for individual variants isn't critical
- You want to show real-time availability and pricing

### Key Characteristic

Keep the URL static and update the displayed data dynamically:

### Implementation Focus

```typescript
const [selectedChild, setSelectedChild] = useState(null);

const handleOptionSelect = (variationId: string, optionId: string) => {
  const newOptions = {
    ...selectedOptions,
    [variationId]: optionId
  };
  
  // Key difference: Update state, not URL
  const childId = getSkuIdFromOptions(
    Object.values(newOptions),
    variationMatrix
  );
  
  if (childId) {
    const child = childProducts.find(p => p.id === childId);
    setSelectedChild(child);
  }
};

// Display dynamic data
const displayProduct = selectedChild || parentProduct;

return (
  <>
    {displayProduct.attributes.name}
    SKU: {displayProduct.attributes.sku || 'Select options'}
    Price: ${displayProduct.attributes.price?.[0]?.amount / 100}
    
    <button 
      disabled={!selectedChild}
      onClick={() => addToCart(selectedChild.id)}
    >
      {selectedChild ? 'Add to Cart' : 'Select All Options'}
    </button>
  </>
);
```

### Pros & Cons

✅ **Fast updates** - No page reloads  
✅ **Smooth UX** - Instant feedback on selections  
✅ **Show availability** - Real-time stock updates  
✅ **Flexible display** - Show/hide unavailable options  
❌ **No variant URLs** - Can't share specific variants  
❌ **Complex state** - More state management required  

## Pattern 3: Hybrid Approach

### Overview

Combine the best of both worlds by updating URLs without full page reloads. This approach provides SEO benefits while maintaining a smooth user experience, ideal for modern storefronts.

### When to Use

- You need both SEO and performance
- Building a modern e-commerce site
- Want shareable URLs without page reloads
- Using a framework that supports client-side routing

### Key Characteristic

Update the URL without page reload while fetching new data:

```mermaid
flowchart TD
    A[User selects option] --> B{All options selected?}
    B -->|Yes| C[Update URL without reload]
    B -->|No| D[Wait for more selections]
    C --> E[Fetch child data via API]
    E --> F[Update UI components]
    
    style A fill:#E3F2FD,stroke:#1976D2,color:#000
    style C fill:#FFF9C4,stroke:#F9A825,color:#000
    style F fill:#C8E6C9,stroke:#388E3C,color:#000
```

### Implementation Focus

```typescript
const [isTransitioning, setIsTransitioning] = useState(false);

const handleOptionSelect = async (variationId: string, optionId: string) => {
  const newOptions = { ...selectedOptions, [variationId]: optionId };
  
  if (!allOptionsSelected(newOptions)) return;
  
  const childId = getSkuIdFromOptions(
    Object.values(newOptions),
    variationMatrix
  );
  
  if (childId) {
    setIsTransitioning(true);
    
    // Key differences:
    // 1. Update URL without reload
    window.history.pushState({}, '', `/products/${childId}`);
    
    // 2. Fetch child data via API
    const response = await getByContextProduct({
      path: { product_id: childId }
    });
    
    // 3. Update displayed product
    setProduct(response.data);
    setIsTransitioning(false);
  }
};

// 4. Handle browser back/forward
useEffect(() => {
  const handlePopState = async () => {
    const productId = window.location.pathname.split('/').pop();
    if (productId !== product.id) {
      // Re-fetch when user navigates
      const response = await getByContextProduct({
        path: { product_id: productId }
      });
      setProduct(response.data);
    }
  };
  
  window.addEventListener('popstate', handlePopState);
  return () => window.removeEventListener('popstate', handlePopState);
}, [product.id]);
```

### Pros & Cons

✅ **SEO-friendly** - Maintains unique URLs  
✅ **Fast UX** - No full page reloads  
✅ **Browser history** - Back/forward navigation works  
✅ **Modern approach** - Best of both patterns  
❌ **Complex implementation** - Most difficult to build  
❌ **State synchronization** - URL and UI must stay in sync

## Pattern 4: Quick Shop Modal

### Overview

Perfect for product listing pages where shoppers can quickly select variations and add to cart without leaving the list. This pattern enhances the shopping experience by reducing navigation.

### When to Use

- Product listing pages or category pages
- Quick add-to-cart functionality
- Mobile shopping experiences
- When browsing flow is more important than deep product details

### Key Characteristic

Show variation selection in a modal without leaving the product list:

### Implementation Focus

```typescript
// In product listing
function ProductCard({ product }) {
  const [showQuickShop, setShowQuickShop] = useState(false);
  
  return (
    
      
      {product.attributes.name}
      <button onClick={() => setShowQuickShop(true)}>
        Quick Shop
      </button>
      
      {showQuickShop && (
        <QuickShopModal
          parentProductId={product.id}
          onClose={() => setShowQuickShop(false)}
          onAddToCart={(childId) => {
            addToCart(childId);
            setShowQuickShop(false);
          }}
        />
      )}
    
  );
}

// Simplified modal logic
function QuickShopModal({ parentProductId, onClose, onAddToCart }) {
  const [selectedChild, setSelectedChild] = useState(null);
  
  // Key differences:
  // 1. Load parent only when modal opens
  useEffect(() => {
    if (parentProductId) {
      loadParentProduct(parentProductId);
    }
  }, [parentProductId]);
  
  // 2. Handle selection in modal context
  const handleOptionSelect = (variationId, optionId) => {
    // Same selection logic, but in modal
    const childId = getSkuIdFromOptions(...);
    setSelectedChild(childId);
  };
  
  // 3. Add to cart without navigation
  const handleAddToCart = () => {
    if (selectedChild) {
      onAddToCart(selectedChild);
    }
  };
  
  return (
    <Modal isOpen onClose={onClose}>
      {/* Variation selectors */}
      <button 
        onClick={handleAddToCart}
        disabled={!selectedChild}
      >
        Add to Cart
      </button>
    </Modal>
  );
}
```

### Pros & Cons

✅ **Quick shopping** - Add to cart without leaving list  
✅ **Maintains context** - Stay on category page  
✅ **Mobile-friendly** - Works great on small screens  
✅ **Reduces navigation** - Fewer page loads  
❌ **No product URLs** - Can't share specific variants  
❌ **Limited space** - Less room for product details

## Summary

Each pattern solves different needs:\n- **Navigation**: SEO and shareable URLs\n- **Dynamic**: Fast, smooth experience\n- **Hybrid**: Balance of both\n- **Quick Shop**: Minimal friction

## Key Takeaways

1. **Choose the Right Pattern**: Use the decision flowchart to select the best pattern for your needs
2. **Consider Your Users**: Different patterns suit different shopping behaviors
3. **Test Performance**: Measure actual performance in your environment
4. **Plan for Mobile**: Ensure your pattern works well on all devices
5. **Handle Edge Cases**: Plan for invalid combinations and loading states

## Next Steps

- [Understanding the Variation Matrix](./variation-matrix-guide.mdx) - Deep dive into the variation matrix structure
- [List Parent & Child Products](./list-parent-child.mdx) - Learn to fetch and display product variations
- [Select a Variation](./select-variation.mdx) - Step-by-step guide to building a variation selector

## References

- [Composable Frontend Example](https://github.com/elasticpath/composable-frontend/tree/main/examples/all-product-types)
- [Catalog API Reference](/docs/api/pxm/catalog)
- [Shopper SDK Documentation](https://github.com/elasticpath/epcc-sdk-js)

---

## Overview(Product-discovery)


Product discovery is the foundation of any commerce experience—it's how your customers find and explore products in your store. Elastic Path provides a comprehensive product discovery system that combines flexible catalog management with powerful search and filtering capabilities.

## What is Product Discovery?

Product discovery encompasses all the ways customers find products in your store:

- **Browsing** through categories and hierarchies
- **Searching** by keywords, attributes, or SKUs  
- **Filtering** by price, brand, size, color, or custom attributes
- **Exploring** related products and recommendations

In Elastic Path, product discovery is powered by the **Catalog API** and **Products API**, which work together to deliver fast, relevant product results to your storefront.

## How Product Discovery Works

### 1. Catalog-Driven Architecture

Elastic Path uses a **catalog-first approach** where:

- **Products** are managed in Product Experience Manager (PXM)
- **Catalogs** are published snapshots of your product data
- **Storefronts** consume catalog data via API calls
- **Real-time overlays** add pricing and inventory context

This architecture ensures your storefront always shows current, accurate product information while maintaining performance.

### 2. Multi-Layered Product Context

When a customer views products, multiple data layers combine:

```
Base Product Data (from Catalog)
+ Price Overlay (from Price Books)
+ Inventory Overlay (from Stock)
+ Localization (from Headers)
= Complete Product Information
```

### 3. Flexible Product Types

Elastic Path supports four product types to match your business needs:

- **Standard Products**: Simple, standalone items (e.g., gift cards)
- **Parent Products**: Containers for variations (e.g., t-shirt in multiple sizes)
- **Child Products**: Individual variants (e.g., t-shirt size M)
- **Bundle Products**: Groups of products sold together with rules

## Key Concepts

### Catalogs vs. Products

**Products** are your master product data—descriptions, images, attributes, and relationships. **Catalogs** are published views of that data, optimized for specific channels, regions, or customer segments.

Think of it this way:
- Products = Your product database
- Catalogs = Your published product pages

### Search and Discovery Context

Every product discovery request includes context that affects results:

- **Catalog ID**: Which published catalog to search
- **Currency**: For price formatting and conversion
- **Locale**: For localized text and sorting
- **Customer Segment**: For personalized pricing or visibility

### Hierarchies and Categories

Products are organized in **hierarchies** (category trees) that help customers navigate your store. A single product can exist in multiple categories, and categories can be nested to create rich browsing experiences.

## Why This Approach Matters

### Performance Benefits

- **Catalog snapshots** eliminate database joins during customer browsing
- **API-first design** enables fast, cacheable responses
- **Overlay architecture** keeps dynamic data (prices, stock) separate from static content

### Flexibility Benefits

- **Multiple catalogs** for different channels, regions, or customer types
- **Headless architecture** works with any frontend technology
- **Extensible data model** supports custom fields and relationships

### Developer Benefits

- **Consistent API patterns** across all product operations
- **Rich filtering options** built into the API
- **Comprehensive relationship support** for complex product structures

## Common Use Cases

### B2C Storefront
- Browse products by category
- Search by keyword or filters
- View product details and variations
- See real-time pricing and availability

### B2B Commerce
- Role-based product visibility
- Customer-specific pricing
- Bulk ordering from product lists
- Integration with procurement systems

### Marketplace Platform
- Multi-vendor product management
- Federated search across sellers
- Dynamic pricing and inventory
- Category-based commission rules

## Next Steps

Now that you understand how product discovery works in Elastic Path, you're ready to implement it:

| To Learn | Go To |
|----------|--------|
| Build your first product listing | [Quick Start Tutorial](./quickstart) |
| Fetch and display products | [List Products](./how-to/list-products) |
| Show product details | [Get Product Details](./how-to/get-product-details) |
| Work with product variations | [Variations Overview](./how-to/variations/overview) |
| Handle product bundles | [Bundles Overview](./how-to/bundles/overview) |

Ready to start coding? Jump into the [Quick Start Tutorial](./quickstart) to build your first product discovery experience.

---

## Quick Start(Product-discovery)


In this tutorial, you'll build a product listing page that fetches and displays products from your Elastic Path catalog.

## What you'll build

A simple product listing that:
- Fetches products from your catalog
- Displays product images, names, and prices
- Handles loading and error states

## Prerequisites

- Node.js 18+ and npm installed
- An Elastic Path store with:
  - Published catalog with products
  - API credentials

## Step 1: Create a Next.js project

This quickstart uses Next.js, but the SDK works with any JavaScript framework.

```bash
npx create-next-app@latest my-elastic-path-store
cd my-elastic-path-store
```

When prompted, choose:
- TypeScript: Yes
- ESLint: Yes
- Tailwind CSS: Yes (for styling)
- App Router: Yes

## Step 2: Install the SDK

Install the Elastic Path Shopper SDK:

```bash
npm install @epcc-sdk/sdks-shopper
```

## Step 3: Set up authentication

Create a `.env.local` file in your project root:

```bash
# Choose your region:
# US East: https://useast.api.elasticpath.com
# EU West: https://euwest.api.elasticpath.com
NEXT_PUBLIC_EPCC_ENDPOINT_URL=https://useast.api.elasticpath.com
NEXT_PUBLIC_EPCC_CLIENT_ID=your-client-id
```

## Step 4: Create the SDK client

Create a new file `lib/epcc-client.ts`:

```typescript
// lib/epcc-client.ts
import { configureClient } from "@epcc-sdk/sdks-shopper";

const endpointUrl = process.env.NEXT_PUBLIC_EPCC_ENDPOINT_URL;
const clientId = process.env.NEXT_PUBLIC_EPCC_CLIENT_ID;

if (!endpointUrl || !clientId) {
  throw new Error('Missing Elastic Path credentials');
}

// Configure the SDK client
export const client = configureClient(
  { 
    baseUrl: endpointUrl 
  },
  {
    clientId,
    storage: "localStorage"
  }
);
```

## Step 5: Create the products page

Replace the contents of `app/page.tsx`:

```typescript
// app/page.tsx
import { getByContextAllProducts } from "@epcc-sdk/sdks-shopper";
import "@/lib/epcc-client"; // Initialize the client

async function getProducts() {
  const response = await getByContextAllProducts({
    query: {
      "page[limit]": 12,
      include: ["main_image"]
    }
  });
  
  return {
    products: response.data?.data || [],
    mainImages: response.data?.included?.main_images || []
  };
}
```

Add the display logic to the same file:

```typescript
// app/page.tsx
import Image from "next/image";
import { extractProductImage } from "@epcc-sdk/sdks-shopper";

export default async function ProductsPage() {
  const { products, mainImages } = await getProducts();

  return (
    
      Products
      
      
        {products.map((product) => {
          const mainImage = extractProductImage(product, mainImages);
          const imageUrl = mainImage?.link?.href || "/placeholder.jpg";
          
          return (
            
              
                <Image
                  src={imageUrl}
                  alt={product.attributes.name}
                  fill
                  className="object-contain"
                />
              
              
              
                {product.attributes.name}
              
              
              
                {product.meta?.display_price?.without_tax?.formatted}
              
            
          );
        })}
      
      
      {products.length === 0 && (
        No products found
      )}
    
  );
}
```

## Step 6: Complete example

Here's the complete page component:

```typescript
// app/page.tsx
import { getByContextAllProducts, extractProductImage } from "@epcc-sdk/sdks-shopper";
import "@/lib/epcc-client"; // Initialize the client
import Image from "next/image";

async function getProducts() {
  const response = await getByContextAllProducts({
    query: {
      "page[limit]": 12,
      include: ["main_image"]
    }
  });
  
  return {
    products: response.data?.data || [],
    mainImages: response.data?.included?.main_images || []
  };
}

export default async function ProductsPage() {
  try {
    const { products, mainImages } = await getProducts();

    return (
      
        Products
        
        
          {products.map((product) => {
            const mainImage = extractProductImage(product, mainImages);
            const imageUrl = mainImage?.link?.href || "/placeholder.jpg";
            
            return (
              
                
                  <Image
                    src={imageUrl}
                    alt={product.attributes.name}
                    fill
                    className="object-contain"
                  />
                
                
                
                  {product.attributes.name}
                
                
                
                  {product.meta?.display_price?.without_tax?.formatted}
                
              
            );
          })}
        
        
        {products.length === 0 && (
          No products found
        )}
      
    );
  } catch (error) {
    return (
      
        Products
        Failed to load products. Please try again.
      
    );
  }
}
```

## Step 7: Run the application

1. Start your development server:
   ```bash
   npm run dev
   ```

2. Open your browser and navigate to `http://localhost:3000`

3. You should see:
   - A grid of products from your catalog
   - Product images, names, and prices
   - Proper error handling if the API fails

## What you've built

✅ A working product listing page  
✅ Integration with Elastic Path Catalog API  
✅ Proper TypeScript types from the SDK  
✅ Error handling and loading states  
✅ Responsive grid layout

## Next Steps

Now that you have a basic product listing, enhance it with:

| Feature | Guide |
|---------|--------|
| Pagination and filtering | [List Products](./how-to/list-products) |
| Product detail pages | [Get Product Details](./how-to/get-product-details) |
| Product variations | [Variations Overview](./how-to/variations/overview) |
| Bundle products | [Bundles Overview](./how-to/bundles/overview) |

## Resources

- [SDK Reference](https://github.com/elasticpath/epcc-sdk-js)
- [API Documentation](https://elasticpath.com/docs/api)
- [Complete Examples](https://github.com/elasticpath/composable-frontend/tree/main/examples)

---

## Developer Tools

## Introduction to API

The Composable Commerce API follows a microservice architecture that enables you to plug commerce into any part of your application. The API is inspired by the [JSON API](http://jsonapi.org/) specification, follows predictable [REST API](https://en.wikipedia.org/wiki/Representational_state_transfer) URLs, and supports [cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing). The two-track [Authentication Layer](/docs/api/authentication) enables destructive and non-destructive actions across projects.

## API Base URLs

Commerce supports multiple geographical regions. For each customer, Commerce accounts and stores are created in a specific region. When you interact with and use the Commerce API, ensure that you use the API end point for the region your store is in. To view the **API base URL** field, go to **System > Application Keys** in **Commerce Manager**.

In the documentation, we use the variable name `<your_elasticpath_api_base_url>` in the sample requests. When making API requests, customers substitute the hostname for the variable.

## Authentication

All requests must include an authentication token in the header. Generate the token by using your API keys.

- To find your API keys, go to **System > Application Keys** section in **Commerce Manager**.
- To use the API to generate a token from your API keys, see the [Authentication](/docs/api/authentication) or [Your first API request](/guides/Getting-Started/your-first-api-request#lesson-1-authenticate) sections.
- To learn more about API keys, see the [Security](/docs/authentication/security#api-authentication-credentials) section.

## OpenAPI Specification for Elastic Path APIs

If you are looking to test or develop with the Composable Commerce API, we recommend using the [Elastic Path OpenAPI collection](/elastic-path-commerce-apis.zip). The collection includes all endpoints.

## Postman Collection for Elastic Path APIs

If you are looking to test or develop with the Composable Commerce API, we recommend using the [Elastic Path Postman collection](/elastic-path-commerce-apis-collection.json). The collection includes all endpoints. Environment variables are included here [postman/environment.json](/postman/environment.json).

## Software Development Kits

Elastic Path officially maintains the following Software Development Kits (SDK) for Composable Commerce. Other community-driven SDKs are available within the [Moltin GitHub](https://github.com/moltin) organization.

### JavaScript SDK

If you are beginning a new project, we recommend that you use the JavaScript SDK for Composable Commerce, which is under active maintenance. Within this guide, the supported endpoints include sample **JavaScript SDK** requests. The Composable Commerce Reference Store is implemented using this SDK.

Get the [JavaScript SDK](https://github.com/elasticpath/js-sdk).

### Composable CLI

The [Composable CLI](/docs/developer-tools/composable-cli/installation) is a command line tool designed to make it easy for you to build Elastic Path-powered frontend experiences. It also enables you to configure various services and integrations provided by Elastic Path.

### Composable Starter

The [Composable Starter](/docs/developer-tools/composable-starter/storefront-starter) is a reference implementation of a storefront built using the Composable CLI. It is a fully functional storefront that you can use as a starting point for your own projects. You can also use it to learn how to build a storefront using Elastic Path products.

### Education resources

You can find a self-serve Composable Commerce API course and other learning opportunities at [Elastic Path Education](https://education.elasticpath.com). Sign in, select the Content Library, and search for `Composable Commerce API`.

---

## Elastic Path MCP Servers

Learn how to set up and use Elastic Path's Model Context Protocol (MCP) offerings to accelerate storefront development with AI-powered tools. This guide covers our Dev MCP server for building React/Next.js commerce applications, our Elastic Path Composable Commerce MCP Server for direct API operations, and our integrations with Context7.

## What are the Elastic Path MCP Servers?

Elastic Path provides specialized MCP servers to support different development workflows:

- **Developer MCP Server**: AI-powered scaffolding for React/Next.js storefront components with curated best practices, designed to eliminate the boilerplate and repetitive tasks that slow down storefront development
- **Elastic Path Composable Commerce MCP Server**: Direct access to Elastic Path API operations for commerce management, automation, and analytics

These servers provide AI agents with the specific context needed to build accurate, production-ready commerce implementations using Elastic Path.

## Developer MCP Server

### How it works

The MCP server exposes a tool called `get-documentation` to your coding agent. This tool has access to a specially created data store of documentation and code examples relating to creating a storefront. In response to your prompts, the tool will locate, rank, and return relevant code snippets and documentation to provide your coding agent with the necessary context to accurately implement a storefront against Elastic Path.

### Quick Start

#### 1. Acquire an access key.

While the Dev MCP Server is in beta, access is restricted. Contact your Elastic Path representative to request an invite and receive your beta key.

#### 2. Configure the Dev MCP Server

Add the Elastic Path Dev MCP server to your IDE configuration. This example is for Cursor IDE (edit `~/.cursor/mcp.json`). For other AI tools, adapt the config as required:

```json
{
  "mcpServers": {
    "elastic-path-dev-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://storefront-agent.vercel.app/mcp",
        "--header",
        "Authorization:${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "your-access-token-here"
      }
    }
  }
}
```

#### 3. Test Your MCP Connection

Test the connection by asking your AI assistant to work on a storefront feature. For example:

```
"Generate a product grid component for my Elastic Path storefront"
```

The MCP server should provide code samples and docs your agent can use to implement your storefront.

:::tip
If the agent does not call the tool, try being more specific; e.g. include 'use the Elastic Path MCP server' in your prompt
:::

### Dev MCP Server Capabilities

The Elastic Path Dev MCP server exposes a `get-documentation` tool with configurable options to tailor responses to your specific development needs:

#### Tool Configuration Options

- **query** (required): Your question or request for documentation/code examples
- **tokens**: Maximum number of tokens to return (default: 5000, controls response length)
- **topic**: Optional focus area to narrow results (e.g., "authentication", "cart management", "payments", "checkout")

The server specializes in generating storefront components and provides:

**Storefront Scaffolding:**

- Product grid components with filtering and pagination
- Shopping cart management with add/remove/update functionality
- Checkout flow components with payment integration
- Customer authentication and account management
- Search and category navigation

**Framework Support:**

- React components with TypeScript
- Next.js pages and API routes
- Tailwind CSS styling
- Elastic Path SDK integration

**Example Prompts:**

```
"Create a product detail page with add to cart functionality"
"Generate a shopping cart sidebar with quantity controls"
"Build a checkout form with Elastic Path Payments"
"Create a customer login/register component"
```

### Best Practices

#### 1. Effective Prompting

Be specific about what you want to generate:

- Mention the framework (React, Next.js)
- Specify styling approach (Tailwind CSS, CSS modules)
- Include functional requirements (responsive, accessible)
- Request error handling and loading states
- Use an appropriate token budget

#### 2. Iterative Development

Start with basic components and enhance:

1. Authenticate your storefront with Elastic Path
2. Generate basic product display page
3. Add cart functionality
4. Implement checkout flow
5. Enhance with advanced features

#### 3. Code Review

Always review generated code for:

- Security best practices
- Performance considerations
- Accessibility compliance
- Code style consistency

---

## Elastic Path Composable Commerce MCP Server

The Elastic Path Composable Commerce MCP Server provides direct access to your Elastic Path commerce platform through the Model Context Protocol. This server enables AI assistants to perform real-time operations across your entire e-commerce infrastructure including orders, products, catalogs, pricing, promotions, and more.

### What You Can Do

The server provides comprehensive access to Elastic Path APIs, enabling you to:

- Query and manage orders with filtering and advanced analytics
- Create and update products with full catalog management
- Browse published catalogs with customer-facing pricing
- Manage pricebooks, promotions, and multi-currency pricing
- Create custom APIs and extend commerce capabilities
- Track sales trends and analyze business performance
- And more...

### Installation & Setup

The Elastic Path Composable Commerce MCP Server can be installed from [npm](https://www.npmjs.com/package/@elasticpath/elasticpath-mcp).

Configure the server in your MCP client with your Elastic Path credentials:

- **EPCC_CLIENT_ID**: Your EPCC application client ID
- **EPCC_CLIENT_SECRET**: Your EPCC application secret
- **EPCC_BASE_URL**: Your EPCC API endpoint (e.g., `https://useast.api.elasticpath.com`)

For detailed installation instructions, configuration examples for different MCP clients, and troubleshooting guidance, please visit the [package on npm](https://www.npmjs.com/package/@elasticpath/elasticpath-mcp).

### Example Use Cases

Once configured, you can ask your AI assistant to perform operations like:

```
"Show me order metrics for the last 30 days"
"Get details for order ABC123"
"Create a new product in the Electronics hierarchy"
"Show me all published catalogs"
"Create a 15% discount promotion for Black Friday"
"Add price modifiers for seasonal discounts"
"Create a custom API for product reviews"
"What's the current USD to EUR exchange rate?"
```

The server handles authentication automatically, manages token refresh, and formats results for easy reading.

---

## Also Available: Context7 Integrations

### What is Context7?

Context7 is a third-party service that indexes documentation and code examples for various libraries and frameworks. It maintains up-to-date, searchable repositories of documentation that AI assistants can access to provide accurate, contextual help. It makes these available via a publically available MCP server.

Context7 has indexed two resources for Elastic Path:

- **Elastic Path API Documentation**: Complete API references, guides, and examples. Wide coverage, less specific, less accurate for coding.
- **Elastic Path Shopper SDK**: Specific, precise usage examples for all methods of the Elastic Path Shopper SDK. Very accurate for coding.

### Context7 Documentation Server

Access comprehensive Elastic Path documentation through Context7:

**Use Cases:**

- When you need detailed API reference information
- Exploring comprehensive documentation beyond what the Dev MCP server provides

### Context7 Shopper SDK Server

Specialized assistance for the Elastic Path Shopper SDK:

**Use Cases:**

- When building custom implementations with the Shopper SDK
- Need specific SDK function examples and usage patterns

---

## OpenAI Product Feeds

## Overview

Catalog Delta Files provide a machine-readable snapshot of only the **changes made since the last publish event**. These files are ideal for feeding external AI platforms such as OpenAI without requiring full catalog re-ingestion.

Typical AI use cases include:

* Semantic search indexing
* AI shopper agents
* AI merchandising agents
* AI-driven recommendations
* Conversational product discovery

---

## How Delta Files Are Generated

Delta files are generated automatically whenever:

* A catalog is published
* A partial republish occurs
* Products, prices, availability, or attributes change

Each delta file contains:

* Product IDs
* Change type (create, update, delete)
* Updated attributes
* Relationships
* Availability and pricing references

Delta files are generated alongside full publish artifacts and follow the same distribution model.

---

## High-Level Data Flow

1. A catalog publish or update is triggered.
2. Elastic Path generates a Catalog Delta File.
3. Your ingestion service retrieves the delta file.
4. The delta data is transformed into OpenAI Product Feed format.
5. The transformed data is sent to OpenAI.
6. OpenAI updates its product index using only the changed records.

---

## Accessing Catalog Delta Files

Delta files are accessed using the same Catalog Publishing process as full exports.

From the Commerce Manager:

1. Navigate to:
   Product Experience Manager → Catalogs
2. Select a catalog.
3. Publish the catalog.
4. Retrieve the generated delta file from the publishing artifacts.

For automated pipelines, delta files should be fetched via your existing catalog publishing automation.

---

## Mapping Elastic Path Delta Data to OpenAI Product Feeds

Each delta entry should be mapped into the OpenAI Product Feed schema.

### Example Mapping

| Elastic Path Field | OpenAI Product Feed Field |
| ------------------ | ------------------------- |
| product_id         | id                        |
| name               | title                     |
| description        | description               |
| sku                | sku                       |
| price              | price                     |
| availability       | availability              |
| images             | images                    |
| attributes         | attributes                |
| delete_flag        | deleted                   |

---

## Handling Change Types

Your ingestion pipeline must handle the three delta operations correctly.

### Create

* Insert a new product record into the OpenAI product index.

### Update

* Replace only the modified fields.
* Retain embedding continuity when possible to avoid re-vectorizing unchanged content.

### Delete

* Remove the product from the OpenAI index.
* Prevent future AI results from referencing inactive products.

---

## Example Delta Processing Workflow

1. Poll catalog publish events or webhooks.
2. Download the delta file.
3. Validate schema and version.
4. Normalize fields.
5. Convert to OpenAI Product Feed format.
6. Send to OpenAI ingestion endpoint.
7. Log processing status and failures.

---

## Best Practices

* Process delta files immediately after publish to minimize AI drift.
* Maintain idempotency in your ingestion service.
* Log every processed delta for audit and replay.
* Version your field mappings to protect downstream AI pipelines.
* Backfill with a full catalog export on schema changes.

---

## Common Use Cases Enabled

* AI-powered site search with minute-level freshness.
* Conversational shopping assistants with accurate availability.
* AI-driven upsell and cross-sell.
* Real-time AI merchandising insights.
* Agentic commerce workflows using product-level reasoning.

---

## Summary

By using **Catalog Delta Files as a native feed for OpenAI Product Feeds**, Elastic Path enables:

* Near real-time AI synchronization
* Lower ingestion and token costs
* Faster AI index updates
* More accurate AI-driven commerce experiences

This bridges the gap between **transactional commerce systems and real-time AI execution**.

### Documentation

* [Catalog Publishing and Delta Files](/docs/commerce-manager/product-experience-manager/catalogs/publishing-catalogs#using-catalog-delta-files)

---

## Storefronts

# Storefronts for Elastic Path

The world of commerce undergoes continuous transformation. As a developer, you have the opportunity to craft integrations for commerce in the diverse spaces where merchants aspire to sell and their customers prefer to make purchases.This guide helps you understand how the Elastic Path composable commerce technology works and how it speeds up the progress of your commerce projects.

---

## Quick Start

<CardSection
id="re"
description="Learn how to get started with an Elastic Path storefront"
>
<Card
title="Creating a storefront"
to="/docs/developer-tools/composable-starter/storefront-starter"
description="Getting started with a storefront"
/>
</CardSection>

## How does a storefront fit into the composable commerce architecture?

Elastic Path Composable Commerce offers a set of versatile products to help you swiftly and effortlessly create unique customer experiences. The storefront, which is the part of what your customers see and interact with, plays a crucial role. It handles tasks like displaying your catalog, managing the shopping cart, and facilitating the checkout process.

With Elastic Path, you have control over designing, building, and managing your storefront. You can use your preferred technology stack and a familiar development framework, enabling faster development. The headless approach allows you to integrate your frontend seamlessly using Elastic Path's modular products, either together or independently. This flexibility addresses your commerce challenges and empowers you to deliver exceptional customer experiences.

## Tools for building storefronts

![composable-frontend-arch.png](/assets/composable-frontend-arch.png)

Elastic Path offers a set of tools to help you build storefronts. You can use these tools together or independently, depending on your requirements.

- Composable CLI
- Composable Starter

### Composable CLI

The [Composable CLI](/docs/developer-tools/composable-cli/installation) is a command line tool designed to make it easy for you to build Elastic Path-powered frontend experiences. It also enables you to configure various services and integrations provided by Elastic Path.

### Composable Starter

The [Composable Starter](/docs/developer-tools/composable-starter/storefront-starter) is a reference implementation of a storefront built using the Composable CLI. It is a fully functional storefront that you can use as a starting point for your own projects. You can also use it to learn how to build a storefront using Elastic Path products.

---

## Bundleinventory

To track inventory at the bundle level (i.e., the total number of complete bundles available), you must use a [SKU-based bundle](/guides/key-concepts/product-experience-manager/bundles#sku-based-bundles). The system will then manage the stock of the bundle as a single unit.

If you do not need to track inventory at the bundle level and instead want to rely solely on the inventory of the individual product options within the bundle, then you do not need to use a SKU-based bundle. This is the approach used for SKU-less bundles.

---

## Bundlepricing

The following table describes the capabilities and pricing that bundles can have.

| Pricing        | Description                                                                                                                                                                                                                                                                                                                                                            | Requires SKU? | Price Book Entry                  | Capabilities                                                                                                                                                                                                                                                                                                                                                                                                                                        |
|:---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Fixed**      | Enables you to assign a fixed price for all the products in a bundle. The bundle can contain items that are available for individual purchase, however, when purchased in a fixed-price bundle, are offered at a discounted price.                                                                                                                                     | Yes           | Mandatory                         | **[Sale Pricing](#sale-pricing)** - defines reduced pricing for the total price of the bundle.**[Volume Pricing](#volume-pricing)** - offers promotional prices for the bundle as a whole when bought in bulk.**Bundle Inventory Management** - bundle inventory can be tracked based on the availability of individual items in the bundle. In this case, the maximum number of bundles you can sell is equal to the number of the option that is least available. |
| **Cumulative** | The price of a bundle can be generated automatically based on the sum of the component products. Each individual product uses its base price, along with any applicable sale pricing or price modifiers. Ensure that you set a price for each product within the bundle. If a component product does not have a price, the bundle price cannot be set and customers cannot purchase the bundle. | Optional      | Not available when SKU is present | **[Sale Pricing](#sale-pricing)** - define reduced pricing for individual products when purchased as part of the bundle. Each product can have a special sale price that will only be used when the product is brought as part of the bundle.                                                                                                                                                                                                       |

### Sale Pricing

#### Fixed Price Bundles
For fixed price bundles, you can set a sale price for the entire bundle. This allows you to offer the bundle at a discounted price compared to the regular bundle price.

#### Cumulative Price Bundles
For cumulative price bundles, you can set a sale price for an item within a bundle so that the product is sold at the sale price when sold as a part of the bundle. Each individual product can use its underlying volume, sale, and normal price, but you can also set a special sale price that will only be used when the product is brought as part of the bundle.

For example, if you have a bundle consisting of four items, you can apply a discounted price to an item within the bundle to get a bundle sales price. Both list and sale price (or was/is prices) are available in the catalog response, enabling you to display slash pricing on your storefront, depending on your requirements.

| Product   | Regular product price | Bundle sales price |
|:----------|:----------------------|:-------------------|
| Product A | $100                  | $80                |
| Product B | $50                   | $50                |
| Product C | $30                   | $30                |
| Product D | $130                  | $130               |
| **Total** | **$310**              | **$290**           |

### Volume Pricing

#### Fixed Price Bundles
For fixed price bundles, you can configure volume pricing for the entire bundle. You can define the price range for different quantities of the bundle, as explained in the following example.

| Bundle Quantity | Price/Each |
|:----------------|:-----------|
| 1-5             | $10.50     |
| 6-10            | $10.00     |
| 11+             | $9.50      |

#### Cumulative Price Bundles

:::warning Volume Pricing Not Supported for Bundle Components
Volume pricing (tiered pricing based on quantity thresholds) is **not supported** for products used as components within bundles. When a product with volume pricing tiers is included in a bundle, those tiers are not applied during bundle price calculation. Volume pricing only works for:
- Standalone products purchased individually
- Fixed-price bundles (pricing applied to the bundle as a whole)
:::

### Pricing for Bundle Components

:::tip Using Sale Pricing for Bundle-Specific Discounts
To apply discounted pricing to products when purchased as part of a bundle, use sale pricing with the `bundle_ids` field. This allows you to create bundle-specific prices for individual components without affecting the standalone product price. This is the recommended approach for implementing sales pricing for products within bundles.
:::

---

## Bundles

### What are Bundles?
A bundle is a distinct, purchasable product formed by grouping one or more other products that you intend to sell together as a single offering. Bundles make it easier for shoppers to discover and purchase multiple related items together, while also helping merchants increase average order value and streamline merchandising.

Bundles are built using components. Components are logical groupings that define how shoppers can select from a set of product options, which are products or sub-bundles available within each group. This structure allows merchants to create everything from simple, fixed sets of products to highly flexible and customizable configurations.

You can have:
- **Fixed Bundles:** These bundles contain a specific, pre-determined set of products with fixed quantities.
- **Dynamic Bundles:** These bundles offer flexibility, allowing shoppers to select their own options or variations from a defined set of choices within the bundle.
- **Bundles of Bundles:** These advanced bundles are composed of other pre-existing bundles. The parent bundle serves only as a logical container (cannot be added to cart directly) and should be used only for complex scenarios where simpler bundle options don't meet your requirements.

There are two different pricing options available:
- **Fixed Pricing:** Assign a specific price to the entire bundle.
- **Cumulative Pricing:** The bundle's price is the sum of the prices of the options selected by the shopper (in a dynamic bundle) or the products defined by the merchant (in a fixed bundle).

### Use Cases

 - **Fixed Bundles:** The "Home Office Essentials" Bundle: An office supply retailer offers a convenient, pre-determined package (desk lamp, mouse, notebook, pens) as a fixed product bundle for easy home office setup, simplifying purchase and potentially increasing order value.
 - **Dynamic Bundles:** The "Build Your Own Latte" Bundle: A coffee shop lets customers create their ideal latte through a dynamic bundle. They select their preferred size, milk, blend, shots, syrups, and extras from a set of options. The price adjusts based on these choices, offering a flexible and tailored drink.
 - **Bundles of Bundles:** The "Couch Configuration" Bundle: A furniture retailer offers couches in different sizes (2-Seater, 3-Seater, etc.), where each size has its own base price and the same customization options (fabric, color, leg style) but with different pricing based on size. The parent bundle lets shoppers first select a couch size, then configure the specific options for that size. Each size-specific bundle must be added to cart individually.

### Terminology

 - **Component:** A Component is a distinct group of one or more product options within a bundle. A bundle consists of one or more components.
 - **Component Min/Max:** The number of products within a Component that can be selected by the shopper, defined through the min and max configuration.
 - **Option:** A Component consists of one or more Options which are distinct products that are added to a component. These products could be a single product, another bundle (in the case of bundles of bundles), a parent product, or a child product. When adding a parent product to a component, all its child products (variations) automatically become available for selection, though you can configure specific child products to be excluded if needed.
 - **Option Default:** A product can be set as default, allowing the merchant to define a pre-selected product for the shopper within a component.
 - **Option Quantity:** Each product in a Component has a specific quantity that the shopper must purchase.
 - **Option Min/Max:** Allows Shoppers to purchase their desired quantity of a product, by configuring the the min and max bounds within an option.

---

## Bundlesku

When creating bundles, PXM offers the flexibility to assign a Stock Keeping Unit (SKU) to the bundle itself or to manage it as a SKU-less entity. 

### SKU-Based Bundles

A SKU-based bundle has a unique SKU. **Fixed Pricing requires a bundle SKU.**

**When to Use a SKU-Based Bundle:**
* **Implementing Fixed Pricing:** To set a single price for the entire bundle.
* **Tracking Bundle Inventory:** To manage stock levels for the complete bundle as a single unit.
* **Applying Direct Bundle Promotions:** To easily target the bundle with discounts using [Promotions Builder](/docs/promotions-builder/overview).

### SKU-Less Bundles

A SKU-less bundle does not have its own unique SKU.

**When to Use a SKU-Less Bundle:**
* **Implementing Cumulative Pricing:** The bundle price changes based on the shopper's selections.
* **Managing Inventory at the Product Option Level:** You only need to track the stock of the individual items within the bundle.

---

## Bundlesof

A Bundle of Bundles is a specialized grouping mechanism that allows merchandisers to organize multiple, related product bundles under a single parent container. **The parent bundle serves only as a logical container and cannot be added to cart directly** - it exists solely to help shoppers navigate to the appropriate child bundle.

> **Important:** Bundles of bundles should be used as a last resort for complex scenarios when simpler bundle options don't meet your requirements. This is the most complex bundle use case and should only be implemented when other bundle types cannot address your specific merchandising needs.

#### Structure

In a Bundle of Bundles, you typically have:

1. A parent bundle with a single component (e.g. "Couch Type")
2. Multiple bundle options within that component (e.g., "2-Seater Sofa Bundle", "3-Seater Sofa Bundle")
3. Each bundle option is itself a complete bundle with its own components and configuration options

When implementing a Bundle of Bundles in your storefront, the parent bundle serves primarily as a navigation aid. Shoppers browse the parent bundle to discover the available bundle options, then select and configure the specific child bundle they're interested in.

For a detailed implementation example, see the [**Couch Collection**](/guides/key-concepts/product-experience-manager/bundles#bundle-of-bundles-couch-collection) example.

![Bundle of bundles](/assets/bundle-of-bundles.png)

#### Requirements

- You cannot have more than one level of child bundles. In other words, a child bundle cannot have a child bundle as a component.
- A parent bundle can contain both bundle and product components.
- Each bundle of bundle option needs to be configured and added to the cart individually.

---

## Components(Bundles)

The following table describes some examples of bundles which are possible in PXM. This is followed by real-life examples of complex bundles.

| Bundle Type               | Pricing                     | Description                                                                                        |
|:--------------------------|:----------------------------|:---------------------------------------------------------------------------------------------------|
| **Pure bundles**          | Fixed                       | Products are available only as a bundle.                                                           |
| **Joint bundles**         | Fixed, Automatic/cumulative | A bundled price offered for two or more products.                                                  |
| **Gift sets**             | Fixed, Automatic/cumulative | A bundle created from a set of predefined items.                                                   |
| **Leader bundle**         | Automatic/cumulative        | A popular product is offered for a discount if you buy it with another less popular product.       |
| **Mix and Match bundles** | Automatic/cumulative        | Bundle products are selected from a predetermined list of items that you can bundle together.      |
| **Upsell bundles**        | Automatic/cumulative        | Discounted price for the current product when bought together with an accessory as a related item. |

### Dynamic Bundle: Customize Your Latte

This example models a customizable latte where the Size component uses variations of a base "Latte" product (Small, Medium, Large) to determine the initial price. Subsequently, the shopper can personalize their latte through optional components (Milk, Blend, Extra Shots, Syrups, Extras). These components consist of individual products that act as upsells or modifications, potentially increasing the final price of the latte.
| Component               | Options                                                                                                                                                                                                           | Default Option | Component Min/Max | Option Quantity | Option Quantity Min/Max |
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|-------------------|-----------------|-------------------------|
| **Size**        | Small ($5.00) Medium ($6.00) Large ($7.00)                                                                                                                                                              | Medium         | 1 / 1             | 1               | N/A                     |
| **Milk**        | Whole ($0.00) Skim ($0.00) Soy (+$0.20) Oat (+$0.20) Coconut (+$0.20)                                                                                                                     | Whole          | 1 / 1             | 1               | N/A                     |
| **Blend**       | Signature ($0.00) Decaf ($0.00)                                                                                                                                                                              | Signature      | 1 / 1             | 1               | N/A                     |
| **Extra Shots** | None ($0.00) One (+$1.00) Two (+$1.50)                                                                                                                                                                  | None           | 0 / 1             | 1               | 1 / 2                   |
| **Syrups**      | None ($0.00) Caramel (+$0.20) Vanilla (+$0.20) Hazelnut (+$0.20) Sugar Free Caramel (+$0.20) Sugar Free Vanilla (+$0.20) Sugar Free Gingerbread (+$0.20) Cinnamon Bun (+$0.20) | None           | 0 / 1             | 1               | 1 / 2                   |
| **Extras**      | None ($0.00) Marshmallow (+$0.50)                                                                                                                                                                            | None           | 0 / 1             | 1               | 1 / 2                   |

### Dynamic Bundle: Build a Couch 
This example demonstrates a "Build a Couch" configuration where the shopper must choose exactly one option from each of the following components: Color, Fabric and Leg Style.
The final price of the Couch will be the sum of the prices associated with the selected option in each of the components.

| Component     | Options                                                                          | Default Option | Component Min/Max | Option Quantity | Option Quantity Min/Max |
|---------------|----------------------------------------------------------------------------------|----------------|-------------------|-----------------|-------------------------|
| **Colour**    | Beige (50.00) Grey ($50.00) Navy Blue ($100.00) Charcoal ($50.00) | Grey           | 1 / 1             | 1               | N/A                     |
| **Fabric**    | Linen ($50.00) Velvet ($50.00) Leather ($150.00)                       | Linen          | 1 / 1             | 1               | N/A                     |
| **Leg Style** | Straight ($75.00) Tapered ($75.00)                                          | Straight       | 1 / 1             | 1               | N/A                     |

#### Cumulative Pricing Example
The final price is the sum of each selected options price from each mandatory component (Color, Size, Fabric).

| Component       | Selected Option | Price ($)  |
|-----------------|-----------------|------------|
| Colour          | Navy Blue       | 100.00     |
| Fabric          | Leather         | 150.00     |
| Leg Style       | Straight        | 75.00      |
| **Total Price** |                 | **275.00** |

### Dynamic Bundles: Outfit Builder
This example demonstrates how a clothing company can implement an Outfit Builder that allows shoppers to configure a complete outfit from a selection of related products within the same collection.

Clothing products are typically modeled as "Parent Products" with [Variations](/guides/key-concepts/product-experience-manager/variations/overview) that represent all possible combinations (sizes, colors, etc.). These parent products can be added to a Bundle Component, which automatically allows shoppers to select any of the parent's child products (variations). 

Additionally, you can configure specific child products to be excluded from the bundle when the parent is added. This gives you fine-grained control over which variations are available for selection within the bundle, while still benefiting from the convenience of adding the parent product.

For example, if you add a "T-Shirt" parent product to a bundle component, all its variations (Small/Red, Medium/Blue, Large/Black, etc.) become available for selection. However, you might want to exclude certain variations (e.g., Small/Green and Medium/Yellow) from this particular bundle. You can configure these specific child products as exclusions, ensuring they won't appear as options even though the parent product is included.

The following table illustrates a Wedding Outfit Builder where each component represents a category of clothing, and each option represents a style variant within that category:

| Component             | Options                             | Default Option  | Component Min/Max | Option Quantity | Option Quantity Min/Max |
|-----------------------|-------------------------------------|-----------------|-------------------|-----------------|-------------------------|
| **Jacket & Trousers** | Single BreastedDouble Breasted | Double Breasted | 1 / 1             | 1               | N/A                     |
| **Shirt**             | Single CuffDouble Cuff         | Double Cuff     | 1 / 1             | 1               | N/A                     |
| **Shoes**             | OxfordDerbyLoafer         | Oxford          | 1 / 1             | 1               | N/A                     |
| **Tie**               | Tie                                 | Tie             | 1 / 1             | 1               | N/A                     |

### Bundle of Bundles: Couch Collection

This example demonstrates how a furniture retailer can implement a "Couch Collection" as a bundle of bundles, where a single component contains multiple couch bundle options. This approach helps to group related couch bundles together for better display on the storefront.

| Component      | Options                                                                | Default Option       | Component Min/Max | Option Quantity | Option Quantity Min/Max |
|----------------|------------------------------------------------------------------------|----------------------|-------------------|-----------------|-------------------------|
| **Couch Type** | 2-Seater Sofa Bundle3-Seater Sofa Bundle4-Seater Sofa Bundle | 2-Seater Sofa Bundle | n/a               | n/a             | n/a                     |

> **Important:** Bundles of bundles cannot be added to cart directly and cannot be configured at the parent level. Each bundle option (like the 2-Seater Sofa Bundle) needs to be configured separately and added to cart individually.

For implementation details on child bundles such as the individual sofa bundles, refer to the **Build a Couch** example above. This example demonstrates how to create a configurable bundle with components for fabric, color, and leg style.

---

## Dynamic

Dynamic bundles allow merchandisers to create configurable product groupings where shoppers can personalize selections within defined rules. These bundles are composed of components—logical groupings of related product options—each with customizable constraints and behaviors. This flexible structure enables tailored experiences, driving higher engagement and average order value.

#### Core Concepts
#### Component Level Rules
Rules can be defined for each component to control shopper selections:

* **Minimum Selections:** Require at least a certain number of products that can be chosen within a component.
* **Maximum Selections:** Limit the number of products a shopper can pick from a component.
* **Optional Components:** Components can also be optional by setting the minimum selection to zero.

#### Product Option Quantity Rules
Merchants can define rules for each product within a component to control shopper purchase quantity:

 * **Default Quantity:** If you do not set a minimum or maximum quantity for a component option, the shopper will be limited to the default quantity that you have set for that specific option within the bundle configuration. This is useful when you want to ensure a specific number of a particular item is included if the shopper selects it.
 * **Minimum Quantity:** This sets the lowest number of units a shopper must select for a product option.
 * **Maximum Quantity:** This defines the highest number of units a shopper can select for a product option.

#### Product Option Defaults
Specific product options can be designated as default within each component. This is particularly useful when the bundle is initially displayed in the cart or when a shopper hasn't yet customized their choices.

#### Parent Products as Options
When working with products that have variations (such as clothing items with different sizes and colors), you can add the parent product to a bundle component. This automatically makes all child products (variations) available for selection within that component.

Additionally, you can configure specific child products to be excluded from the bundle when the parent is added. This gives you fine-grained control over which variations are available for selection within the bundle, while still benefiting from the convenience of adding the parent product.

For example, if you add a "T-Shirt" parent product to a bundle component, all its variations (Small/Red, Medium/Blue, Large/Black, etc.) become available for selection. However, you might want to exclude certain variations (e.g., Small/Green and Medium/Yellow) from this particular bundle. You can configure these specific child products as exclusions, ensuring they won't appear as options even though the parent product is included.

#### Bundle Configuration in Catalog and Cart

Dynamic bundles have a `bundle_configuration` which describes the options selected by a shopper. This configuration is crucial for both displaying bundle options in your catalog and processing bundle purchases in your cart.

##### Bundle Configuration Structure

The `bundle_configuration` is a JSON object that contains:

- `selected_options`: An object where each key is a component ID (e.g., "size", "color", "extras")
  - Each component contains key-value pairs where:
    - The key is the product ID of the selected option
    - The value is the quantity of that option

##### Working with Bundle Configurations in Catalogs

1. Once your bundles are [published in a catalog](/docs/api/pxm/catalog/publish-release), a shopper can select the products they want.
2. Use [Get a product in a catalog release](/docs/api/pxm/catalog/get-by-context-all-products) to check a bundle's default configuration. The default `bundle_configuration` is returned in the `meta` section of the response.
3. Use the [configure a shopper bundle](/docs/api/pxm/catalog/configure-by-context-product) endpoint to store a shopper's selections.

When adding a dynamic bundle to a cart, you need to include the `bundle_configuration` in the cart item. This ensures that the correct products and quantities are added to the cart.

---

## Custom Attribute Spec Summary

### Custom Attributes

Custom attributes allow you to extend the data model with your own key-value data. They are supported on products, hierarchies, nodes, and prices.

You can define up to 100 custom attributes in each group (`shopper_attributes` and `admin_attributes`). Both keys and values must be strings. Attribute names must be no longer than 64 characters and can only contain alphanumeric characters, underscores, and hyphens. Values must be no longer than 512 characters.

- `shopper_attributes` are visible in shopper-facing catalogs and accessible to both shoppers and administrators. Ideal for customer-facing data, such as promotional labels or product tags.
- `admin_attributes` are private and not visible in catalogs. Best suited for internal operational data, such as cost tracking or workflow metadata.

See [Custom Attributes](/guides/key-concepts/product-experience-manager/custom-attributes/).

---

## Hierarchies(Hierarchies)

Use hierarchies to organize your products into categories and sub-categories. Define hierarchies that work for the products in your store.

A hierarchy is a tree structure that consists of a root node with 1 or more parent nodes. Each parent node can also have one or more children nodes, and so on, creating a parent-child relationship between nodes.

![Hierarchy Nodes](/assets/heirarchynodes.png)

A product can belong to multiple nodes in multiple hierarchies. The following example of Elpa basketball shoe for men shows different hierarchies and nodes that the product might be in:

- Brands > **Elpa**
- Shoppers > **Men**
- Shoes > Sports > **Basketball**

The root of a hierarchy specifies the aspect of the product data that the hierarchy displays. For example, root can be categories, brands, types, or manufacturers of the products. You cannot assign products to a root node.A node in a hierarchy contains products grouped in a specific theme, such as a products from a specific brand.

## Characteristics of Hierarchies and Nodes

Below is an example of a hierarchy and its nodes.

![Hierarchy Example](/assets/hierarchexample.png)

- Sibling nodes are nodes with the same parent. Sibling nodes must have unique names and unique slugs. The nodes **Electric Ranges** and **Gas Ranges** are siblings. They must have unique names and slugs.
- Nodes that are in different locations in a hierarchy, or across multiple hierarchies, do not need unique names and slugs.
- If you move the **Electric Ranges** node to the **Built-in** node, all the children of the **Electric Ranges** node also move to the **Built-in** node.
- The **Double Oven** nodes can have the same name because they have different parents.

Once you have created your products, (for more information, see [**Products API**](/docs/api/pxm/products/create-product) or [Hierarchies](/docs/commerce-manager/product-experience-manager/hierarchies/overview) in Commerce Manager), you can use Hierarchies to organize your products.

- You can associate products with nodes. You cannot associate a product with the root node. For more information, see [**Create Node Product Relationships**](/docs/api/pxm/products/create-node-product-relationship).
- You can duplicate an existing hierarchy. This is useful because it enables you to quickly and easily create multiple hierarchies with the same node structure. Any nodes in the existing hierarchy are also created in the duplicated hierarchy. In addition, you can optionally specify whether you want products associated with the nodes in an existing hierarchy to be associated with the nodes in the duplicated hierarchy. See [**Duplicate a Hierarchy**](/docs/api/pxm/products/duplicate-hierarchy).
- You can move an existing node to a different location within the same hierarchy by changing its parent node. If the node has child nodes, they retain their relationship with the moved node. In other words, the node and all its children move to the new location in the hierarchy. For more information, see [**Create a Node in a hierarchy**](/docs/api/pxm/products/create-node).
- If your store supports multiple languages, you can localize new and existing hierarchies and nodes.

---

## Hierarchycatalogs

The hierarchies determine which products appear in the catalog. When you create a catalog, you specify one or more hierarchies. Only the products that are associated with the selected hierarchies are included in the catalog. Your Front-end developers use the hierarchies to create and populate navigation menus in your storefront. You can improve how your customers search your store using the Catalog View API.

You can also specify the order you want your hierarchies to display in a published catalog. You can order your hierarchies on a catalog-by-catalog basis.

![Hierarchy_sorting](/assets/hierarchy_sorting.png)

---

## Export

You can use product export to export your products in Product Experience Manager. Export builds a `.csv` file containing the product entries. A `.csv` file can contain up to 10,000 product entries. If you have more than 10,000 product entries, then another `.csv` file is created and so on, until all your products are exported.

You might have specified custom extension data in a `.csv` file when you imported the products. These modifications are all exported. So, when you send a request to the Export API, the `.csv` file, included in the Job endpoint response, reflects any changes that you have made. For more information, see [Exporting Custom Data (Flows)](/docs/api/pxm/products/product-export#exporting-custom-data-flows).

When you send a product export request, a job is created. Jobs are processed one at a time. You can continue to send product export

requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See [**Jobs**](/docs/api/pxm/products/jobs) API or [Jobs](/docs/commerce-manager/product-experience-manager/jobs/) in Commerce Manager.

After the files are exported, you get a link to the location where the `.csv` files are stored. You can then make any changes to the product fields (modify product information, add main image files, and custom extension data) in your exported `.csv` files. See [**Product Export CSV File**](/docs/api/pxm/products/product-export#product-export-csv-file).

Once you are happy with your changes, you can import the updated `.csv` files using product import. See [**Product Import/Bulk Update**](/docs/api/pxm/products/product-import-bulk-update).

---

## Import

You can use Product Import to:

- Add new products. For new products that you want to add, the entry in the .csv file must have an external_ref that does not match any existing products.

- Add new:

    - main image files. See [**Importing Main Image Files**](/docs/api/pxm/products/product-import-bulk-update#using-imported-main-image-files).
    - custom data. See [**Importing custom data**](/docs/api/pxm/products/product-import-bulk-update#importing-custom-data-flows).
    - Make bulk updates to existing products, main image files, and custom data.

- Update existing products, including images, templates/flow fields and entries. The entry in the .csv file must have a unique `id` and/or `external_ref` that matches the `id` and `external_ref` of the existing product you want to update. You may have both a unique `id` and `external_ref`, but you must have at least one.

You cannot use product import to:

- Delete existing products.
- Import product bundles.

Product Import uses a [**Comma Separated Values (CSV)**](/docs/api/pxm/products/product-import-bulk-update#characteristics-of-csv-import-files) file to import/update products, main image files, and custom extension data. See an [example file](/assets/pim_product_import_example.csv).

When you send a product import request, a job is created. Jobs are processed one at a time. You can continue to send product import requests, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed. See [**Jobs**](/docs/api/pxm/products/jobs) API or [Jobs](/docs/commerce-manager/product-experience-manager/jobs/) in Commerce Manager.

We recommend that you include the maximum allowed number of products in each `csv`file (for example, up to 50,000 rows or a file size of 50 megabytes, see [**Comma Separated Values (CSV)**](/docs/api/pxm/products/product-import-bulk-update#characteristics-of-csv-import-files)) to minimize the number of files you submit. This helps prevent extended waiting times for processing jobs.

---

## Jobs(3)

Several Product Experience Manager endpoints function as jobs. When any of these endpoints are run, a job is automatically created.

- product [**import**](/docs/api/pxm/products/import-products).
- product [**export**](/docs/api/pxm/products/export-products).
- price book [import](/docs/api/pxm/pricebooks/import-a-price-book-and-prices).
- [**duplicating hierarchies**](/docs/api/pxm/products/duplicate-hierarchy).
- [**building child products**](/docs/api/pxm/products/build-child-products).

#### Characteristics of Jobs

Jobs have the following characteristics.

- Jobs are asynchronous.
- Jobs have a different status, depending on where a job is in its lifecycle. See [**Job Lifecycle**](#job-lifecycle).
- Jobs include the data used when an endpoint is run.
- Jobs are processed one at a time. You can continue to send requests using endpoints that function as jobs, but those jobs are queued. In other words, Commerce looks for any jobs that have a status of PENDING and starts the job with the earliest created date. This process is repeated until all jobs are processed.
- Jobs report messages and/or errors to help you understand:

    - what changes a job implemented in Commerce.
    - the reasons for any failed jobs.

#### Job Lifecycle

A job has the following lifecycle.

![job lifecycle](/assets/job-lifecycle.png)

- **PENDING** - Commerce has received the request but is currently busy processing other requests.
- **STARTED** - Commerce has started processing the job.
- **SUCCESS** - The job has successfully completed.
- **FAILED** - The job has failed. See [**Get job errors**](/docs/api/pxm/products/get-all-jobs).

---

## Catalogs(Products)

For a product to appear in the store, the product must be in a `live` state. By default, a product is created in the `draft` state. This is to ensure that the product details are reviewed and approved before publishing it. When you publish a catalog, only the live products appear in the catalog release. If you change a product's state to live, you must republish the catalog for the product to be displayed in the catalog.

In addition, a product must belong to at least one hierarchy. When you publish a catalog, the live products in the hierarchies appear in a catalog release. A catalog can have one or more hierarchies of products. The hierarchies contain all the products that you want to display in your store. Only the products that are associated with nodes in the selected hierarchies are included in the catalog. You can create your hierarchies and nodes when configuring your products.

---

## Localization

You can localize product names and descriptions when creating your products and hierarchies. Localizing your products and hierarchies enables you to expand your reach to diverse markets. Adapting your product names and descriptions to meet linguistic requirements improves customer satisfaction and enhances brand loyalty.

You can do this when creating your products and hierarchies.

- using the API. See [Create a product](/docs/api/pxm/products/create-product) and [Create a hierarchy](/docs/api/pxm/products/create-hierarchy).
- using Commerce Manager. See [Using Locales](/docs/commerce-manager/product-experience-manager/locales/).

---

## Personalizing

You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages. You can do this by configuring the the `custom_inputs` attribute.

---

## Productsoverview

Products are the items or services that you might want to sell in your store. In Product Experience Manager, a product has a name, description, ID, and SKU. Products can also have additional attributes and associated rich media assets, such as product images or a file containing additional product details. If your store supports multiple languages, you can localize product names and descriptions.

Product data is stored in a database. After you add products, you can update product information, add images and other assets, and associate products with one or more hierarchy nodes. You can export the updated product information back to other business systems so that your organization sees a consistent view of products.

While defining products, the products are in a draft state. Your organization can develop the criteria and business processes to help determine when a product is ready to go live and appear in a catalog.

To appear in a catalog, a product must meet the following criteria:

- The product is live.
- The product is associated with at least one hierarchy.
- The catalog references a hierarchy that includes the product.

---

## Tags

You can use product tags to store or assign a key word against a product or service that you sell in your store. The product tag can then be used to describe or label that product. Product tags represent similarities between products who do not share the same attributes. Using product tags means that you can group your products together, for example, by brand, category, subcategory, colors, types, industries, and so on. For example, a 3rd party manufacturer may sell cases for Apple iPads whose products would not be returned when filtering on the **Apple** brand. However, merchandizers can tag the cases with **Apple** so that the cases are returned along with other **Apple** products.

- As a merchandizer, you can enhance your product list using tags, enabling you to refine your product list and run targeted promotions. Using the example above, you can have a clearance sale of **Apple** accessories, by tagging your products accordingly.
- As developers, you can use tags to enrich your search solution, reducing the amount of time and effort needed to keep your search solution up to date.

A typical use case for product tags is to categorize your products based on color. For example, you could tag the products that you sell in your storefront with a color. Your shoppers can then search your products by color, enabling shoppers to quickly find what they are looking for, increasing the likelihood of a purchase, and boosting conversion rates.

![blue shoes](/assets/blue_shoes.png)

### Characteristics of Product Tags

Product tags have the following characteristics:

- A product can have up to 20 tags.
- A product tag can be up to 255 characters.
- Product tags must not contain any spaces or commas.

---

## Types

Commerce automatically assigns types to the products you create. In Commerce Manager, you can see at a glance the product types in a list of a products. In addition, you can filter on product types in both the API and Commerce Manager.

Product types can also be used in catalogs. For example, in your catalog, you can filter on `parent` so that only your parent products are displayed in your storefront.

Products have one of the following types:

* `standard` - Standard products are a standalone products.
* `parent` - A parent product is a product that has child products that have been built in Commerce Manager or using the [**Build Child Products**](/docs/api/pxm/products/build-child-products) endpoint.
* `child` -  When you configure product variations and variation options for parent products, the child products derived from the parent products are automatically created in Commerce.
* `bundle` - A bundle is a purchasable product, comprising one or more standalone products (in other words, `components`) to be sold together.

:::note
In Commerce Manager, `standard` products are called **Product**.
:::

---

## Extendingproducts

With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. You can create templates for your products at both the organization and store level.

### Product Templates

Templates are a collection of attributes. Attributes are grouped together to match a particular product type or to provide an input for other purposes, such as Search Engine Optimization (SEO) or product specification. For example, a *Book* template might contain the attributes, such as *ISBN*, *Author*, *Number of pages*, *Year Published*, or *Condition (New/Used)*.

You can create product templates for both organization and store. However, stores can use organization templates for store level products.

### Product Attributes

Use attributes to define the characteristics of products in a store. For example, you can assign attributes such as, *care instructions* or *fabric*, to a shirt. When a shopper searches for a specific item, attributes help stores to return the products that match the search criteria. For example, when a shopper searches for a large blue shirt, all shirts that are large and blue are returned as the search result.

---

## Buildchildproducts

With product variations in Product Experience Manager, you can create product variations and different options for each variation and use both to create child products for a product. Each child product is a unique combination of options associated with the product.

Child products inherit attributes from their parent products. When you make changes to the attributes of the parent products, you can rebuild your child products, ensuring that changes to the parent products are propagated to the child products.

Alternatively, you can modify a child product independently, without impacting its parent product. For example, you may prefer the status of your child product to be `live`, while keeping the parent product's status as `draft`. When you directly update a child product, it becomes independent of its parent product. In other words, any subsequent changes made to the parent product are not automatically reflected in the child product when you rebuild the parent product and its child products. Once a child product is independent of its parent, you cannot recreate the association between the child product and its parent. You must delete the child product and rebuild the parent to recreate the child product.

Following on from that, if you add the same flow to both a parent and child product, the child flow values are not affected by changes to the parent flow values in a rebuild.

Building child products is an asynchronous operation. When you build child products, a job is created. The jobId of the job is displayed in the response. When the job is complete, the build child products operation is also complete. You can use the jobId to see the status of your job using the [`Get a Job`](/docs/api/pxm/products/get-job) endpoint or see [Jobs](/docs/commerce-manager/product-experience-manager/jobs/) in Commerce Manager.

### Using Build Rules

When building your child products, you can build all products related to a product.

Alternatively, you can build a combination of child products associated with a product, based on build rules that you specify. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. You can do this using `build_rules`. `build_rules` are combinations of variation option IDs that you wish to include or exclude when building your child products. See [Build Child Products](/docs/api/pxm/products/build-child-products) endpoint or [Building Child Products](/docs/commerce-manager/product-experience-manager/variations/#building-child-products) in Commerce Manager.

---

## Childproducts

Child products inherit attributes from their parent products. When you make changes to the attributes of the parent products, you can rebuild your child products, ensuring that changes to the parent products are propagated to the child products.

Alternatively, you can modify a child product independently, without impacting its parent product. For example, you may prefer the status of your child product to be `live`, while keeping the parent product's status as `draft`. When you directly update a child product, it becomes independent of its parent product. In other words, any subsequent changes made to the parent product are not automatically reflected in the child product when you rebuild the parent product and its child products. Once a child product is independent of its parent, you cannot recreate the association between the child product and its parent. You must delete the child product and rebuild the parent to recreate the child product.

Following on from that, if you add the same flow to both a parent and child product, the child flow values are not affected by changes to the parent flow values in a rebuild.

In addition, when building your child products, you can choose to exclude or include certain combinations of variation options. This is useful, for example, if you have a variation option that you do not sell. This makes managing and building your child products quick and easy. See [**Build child products**](/docs/api/pxm/products/build-child-products).

Re-building child products after adding or removing a new variation changes the total number of child products that you can generate from a base product. When you rebuild the child products after updating variations associated with the base product, all existing child products that belong to a base product are deleted. New child products are created with new product IDs.

If you have any bundles that reference child products directly, then you must update the bundles with the new child product IDs.

However, re-building child products after adding or removing an option does not change the existing product IDs.

---

## Pricemodifiers

You can use price modifiers to change the price property of child products. By default, child products inherit the same price as their base products. Using price modifiers, you can enable child products to inherit a different price. This enables you to configure the price of child products, for example, to be lower than its base product, without having to individually update the price of your child products. There are three types of price modifier.

Modifier | Data Type | Effect |
| :--- | :--- | :--- |
| `price_increment` | `string` | Increases the price of a product. |
| `price_decrement` | `string` | Decreases the price of a product. |
| `price_equals` | `string` | Sets the price of a product to the amount you specify. |

The following is an overview of the steps you need to follow to use price modifiers.

1. Create a price modifier. You must give the price modifier a unique name, for example, tax_modifier.
1. Create a product modifier that uses the same name as the price modifier.
1. [**Build your child products**](/docs/api/pxm/products/build-child-products) with the new product modifier.

---

## Productmodifiers

Use modifiers to change the properties of child products that are inherited from a base product. With modifiers, you only need to have one base product with a variation attached to the product.

Modifiers attached to a variation option are applied to a base product to create child products. For example, instead of creating three base products for three different shirt colors, you can do the following:

1. [**Create a parent product**](/docs/api/pxm/products/create-product), *shirt*, with the variation, *color*, attached to it.
1. Create three options for the *color* variation. See [**Create a variation option**](/docs/api/pxm/products/create-variation-option).
1. [**Create a modifier**](/docs/api/pxm/products/create-modifier) for each option to change the properties of each child product. For example, attach a *description append* modifier to each option so that each child product has different description based on the color of the child product.
1. [**Build the child products**](/docs/api/pxm/products/build-child-products).

This screenshot provides an example of a child product of *shirt* which has a specific description associated with it because of the *description append* modifier setting for the option *yellow*:

![Child products with different descriptions](/assets/modifier-description-append.png)

---

## Variationsoverview

Product variations are the product options available for a base product that your shoppers can choose. As a merchandiser, you want to be able to present all the options you have available for your products to make it easier for your shoppers to visualize them and influence a potential sale. Product Variations allow you to create and manage up to 10,000 unique combinations of options for variations of a product. You can then use PXM Catalogs to build different catalogs for different users, giving you greater flexibility with your product data and making it easier for your shoppers to interact with your products.

For example, a product has two variations size and color. The size variation has three options, such as small, medium, and large and the color variation has three options, such as green, red, and blue. This creates a variation matrix with nine possible unique combinations or child products as shown in the following example:

![The sizes are across the top row and the colors are in the first column.](/assets/product-variations-1.png)

You can create additional variations or options and attach them to a product to increase the number of combinations. Using the previous example, if you add a third variation with three options, you can build child products with 27 unique combinations of variations and options.

---

## Variationsreusability

Variations are reusable, and you can attach the same variation to any number of products. You can also create a link between the existing variation and a new product. The following scenario provides an example:

1. Create a variation `shoe size` and add five options in the variation.
1. Create a product `shoe 1` and link the variation `shoe size` to the product.
1. Create second product, `shoe 2` and link the variation `shoe size` to this product as well.
1. Create a third product `shoe 3` and do not link any variation to this product.

`shoe 1` and `shoe 2` inherit the properties of `shoe size` variation, allowing you to build child products with these options. However, you cannot build child products for `shoe 3` unless you assign a variation with at least one option to the product.

---

## Enabling the Gateway in Commerce Manager

For Elastic Path Commerce Cloud, follow the steps below to enable the gateway. To set up the Stripe plugin for Elastic Path Commerce, follow the instructions in [Configuring the Plugin](https://documentation.elasticpath.com/stripe/docs/configuring.html) documentation.

## Prerequisites

- Ensure that you are [onboarded](/docs/payments/onboarding) to Elastic Path Payments Powered by Stripe.
- Log in to [Stripe Dashboard](https://dashboard.stripe.com/login) and make a note of your stripe Account ID.

## Procedure

1. Go to Commerce Manager.
1. Go to **SYSTEM > Store Settings > Payment Gateways**. A list of payment gateways that are available is displayed. Initially, the status of **Elastic Path Payments powered by Stripe** is **Disable**.
1. Click **Elastic Path Payments powered by Stripe**. The **Edit Elastic Path Payments powered by Stripe** page is displayed.
1. Enter your Stripe **Account ID**.
1. Select **Enabled** checkbox to make **Elastic Path Payments powered by Stripe** available in Commerce Manager.
1. (Optional) Select **Test mode** checkbox to use test payment method. **Test mode** checkbox must be cleared to enable **Elastic Path Payments powered by Stripe** in a production environment.
1. Click **Save**. The status of **Elastic Path Payments powered by Stripe** is now **Enabled**.
1. (Optional) Disable **Elastic Path Payments powered by Stripe** at any time by closing your account or clearing the **Enabled** checkbox on the **Edit Elastic Path Payments powered by Stripe** page.

## Demos

<iframe width="560" height="315" src="https://www.youtube.com/embed/4MjIofAjRao" title="Configuring Elastic Path Payments powered by Stripe" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Elastic Path Payments Powered by Stripe(Payments)

Elastic Path Payments Powered by Stripe gateway interacts with Stripe to allow your shoppers to pay for an order during their purchases. It supports both Elastic Path Commerce and Elastic Path Commerce Cloud.

To use the Elastic Path Payments Powered by Stripe gateway, reach out to your Customer Success Manager or [Customer Success Team](mailto:customersuccess@elasticpath.com).

Create your Stripe account in [Stripe Dashboard](https://dashboard.stripe.com/login) and complete an onboarding form to make payments using the gateway. For more information, see [Onboarding](/docs/payments/onboarding).

Once you have signed up for Elastic Path Payments Powered by Stripe, you must configure the payment gateway so that your shoppers can make payments.

:::note
- If you are using Elastic Path Commerce Cloud, follow the steps in [Configure Elastic Path Payments Powered by Stripe](/docs/api/payments/update-ep-payments-stripe) documentation. For an overview of how payments work in Elastic Path Commerce Cloud, see [Payments](/docs/api/carts/payments).
- If you are using Elastic Path Commerce, see [Elastic Path Commerce Plugin Integration](https://documentation.elasticpath.com/stripe/docs/index.html). The payment gateway supports Elastic Path Commerce 8.3 or later.
:::

## Related Resources

See [Payments Using Stripe](https://learn.elasticpath.com/learn/course/internal/view/elearning/137/epcc261-payments-using-stripe) course in the learning center. You must log in to access the course.

---

## Onboarding

## Prerequisites

Contact your Customer Success manager or [Customer Success team](mailto:customersuccess@elasticpath.com) to get an onboarding link to set up the Stripe account. The link can only be used once and expires in seven days.

## Procedure

1. Click the onboarding link provided by the Elastic Path platform admin.

    :::note
    The onboarding forms are subject to change. Follow the on-screen instructions when you click the onboarding link. You may be required to provide personal information and business details about your company and industry.
    :::

1. Enter your **Email** that you previously provided to the Elastic Path platform admin to create an onboarding link.
1. Click **Continue**.
1. Enter your **Password**, and click **Continue**.
1. Enter your mobile number and click **Send text** to get a verification code.
1. Enter the 6-digit verification code, and click **Next**.
1. On the **Let’s start with some basics** page, choose your **Registered business address** and **Type of business**, and then click **Continue**.
1. On the **Personal details** page, enter a few details about yourself, and click **Continue**.
1. On the **Business details** page, choose your **Industry**, enter **Business website**, and type **Product description**.
1. Click **Continue**.
1. On **Select an account for payouts** page, enter your banking information, and click **Continue**.
1. On the **Customer support details** page, enter **Statement descriptor**, **Shortened descriptor**, and **Customer support phone number**. This helps customers to identify your business.
1. Click **Continue**.
1. Review your details, and click **Submit**. You are now successfully onboarded to Elastic Path Payments.
1. Login to [Stripe Dashboard](https://dashboard.stripe.com/login) and go to **Settings**.
1. Under **Business settings**, click **Account details** and make a note of your Account ID.

---

## Stripe Elements

We support Stripe Elements and recommend that you use the payment method or [source](https://stripe.com/docs/api/sources) with Stripe payments. For more information about generating a payment method on the client-side, see the [Stripe Elements](https://stripe.com/docs/payments/elements) documentation.

Refer to Stripe [Checkout](https://stripe.com/docs/payments/checkout/how-checkout-works) documentation to see how the checkout works.

---

## Anonymize usages

You can anonymize promotion usage.

When anonymization is successful, Personal Identifiable Information such as `customer_email` address is replaced with `*`.

## `POST` Anonymize Usages

```http
https://useast.api.elasticpath.com/v2/promotions/usages/anonymize
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. The grant type must be `client_credentials`. |

### Body

| Name   | Required | Type     | Description |
|:-------|:---------|:---------|:------------|
| `usage_ids` | Required | `array [string]` | The unique identifiers of the usages to be anonymized. You can anonymize multiple usages at the same time. |

## Request Example - Curl

```bash
curl -X POST https://useast.api.elasticpath.com/v2/promotions/usages/anonymize \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $ {
      "data": {
        "usage_ids": ["ca4385ec-7fb2-4a95-8690-f752c508d68a"]
  }
}
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "id": "ca4385ec-7fb2-4a95-8690-f752c508d68a",
            "order_id": "8edd5ca8-39b7-468d-aea9-a470690ca98d",
            "code_id": "00fc633b-9932-4e18-b122-fd5c3173caa3",
            "code": "node1off",
            "times_used": 1,
            "used_on": "2023-06-19T18:05:20.846Z",
            "customer_id": "9ef25142-d67a-41d3-99b2-4d30aeef6c9d",
            "customer_email": "**",
            "meta": {
                "timestamps": {
                    "updated_at": "2023-06-19T18:05:39.141Z"
                }
            },
            "updated_by": "Key-2439657140697170361",
            "anonymized": true
        }
    ]
}
```
## Errors

The following response is returned if some `usage_ids` are successfully anonymized and if some `usage_ids` are not valid. The invalid `usage_ids` are returned in the `errors:[]` array.

```json
{
    "data": [
        {
            "id": "6a847eba-aec1-4d35-b43a-c9ff7f14e3e3",
            "order_id": "2ff49239-3a3c-4877-8611-37515aac20c2",
            "code_id": "00fc633b-9932-4e18-b122-fd5c3173caa3",
            "code": "node1off",
            "times_used": 1,
            "used_on": "2023-06-16T17:38:11.403Z",
            "customer_email": "**",
            "meta": {
                "timestamps": {
                    "updated_at": "2023-06-16T18:14:14.218Z"
                }
            },
            "anonymized": true
        }
    ],
    "errors": [
        {
            "status": "404",
            "title": "Could not anonymize some usages",
            "detail": "Usages not found.",
            "meta": {
                "usage_ids": [
                    "6a847eba-aec1-4d35-b43a-c9ff7f14e3e4"
                ]
            }
        }
    ]
}
```

---

## Get a Promotion Code Usage

## `GET` Get a Promotion Code Usage

```http
https://useast.api.elasticpath.com/v2/promotions/:id/codes/:code-name/usages
```
Use this endpoint to track the usage history of a specific promotion code within the specific promotion. For example, `order_id`, `code`, `times_used`.

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
| ---- | -------- | -------- | -------------------------------- |
| `id` | Required | `string` | Specifies the unique identifier for the promotion. |
| `code-name` | Required | `string` | Specifies the name of the code. For example, `10OFF`.  |

### Headers

| Name            | Required | Type     | Description                                         |
| --------------- | -------- | -------- | --------------------------------------------------- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Query parameters

| Name | Required | Type     | Description                      |
| ---- | -------- | -------- | -------------------------------- |
| `filter` | Optional | `string` | Filter attributes. For more information, see [Filtering](#filtering). |
| `page[limit]`  | Optional | `integer` | The number of records per page. |
| `page[offset]` | Optional | `integer` | The number of records to offset the results by. |
| `sort` | Optional | `string` | Supported attribute is `used_on`. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with -, for example, -used_on. The default sort order is `used_on` in ascending order. See [Sorting](/guides/Getting-Started/sorting). |

## Filtering

| Attribute | Type | Operators | Example  |
| ---------| --------- | ---------------------------| -------- |
| `code` | `string` | `eq` | `eq(code,cart1off)` | 
| `id` | `string` | `eq` | 
| `used_on` | `string` | `gt`,`ge`,`le` and `lt` | `gt(used_on,2023-07-11)` |

## Request Example

```bash
curl https://useast.api.elasticpath.com/v2/promotions/:id/codes/:code-name/usages \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "id": "a042bd4b-21a6-4f55-8add-5a3e8b862ddc",
            "order_id": "01e2a292-f92e-4579-973c-2f3bc70acec1",
            "code_id": "7905c48a-55b0-4bf0-abd7-c2cdbbb944e9",
            "code": "cart2uses",
            "times_used": 1,
            "used_on": "2023-05-30T23:10:56.016Z",
            "customer_id": "1eaf092c-f6e1-48e6-a64f-1c092b711916",
            "customer_email": "test@email.com",
            "meta": {
                "timestamps": {
                    "updated_at": "2024-01-03T17:37:47.111Z"
                }
            },
            "anonymized": false
        }
    ]
}
```

---

## Get Usages for Promotion

## `GET` Get Usages for Promotion

```http
https://useast.api.elasticpath.com/v2/promotions/:id/usages
```
Use this endpoint to track the usage history of the specific promotion. For example, `order_id`, `code`, `times_used`, and so on.

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
| ---- | -------- | -------- | -------------------------------- |
| `id` | Required | `string` | Specifies The unique identifier for the promotion. |

### Headers

| Name            | Required | Type     | Description                                         |
| --------------- | -------- | -------- | --------------------------------------------------- |
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Query parameters

| Name | Required | Type     | Description                      |
| ---- | -------- | -------- | -------------------------------- |
| `filter` | Optional | `string` | Filter attributes. For more information, see [Filtering](#filtering). |
| `page[limit]`  | Optional | `integer` | The number of records per page. |
| `page[offset]` | Optional | `integer` | The number of records to offset the results by. |
| `sort` | Optional | `string` | Supported attributes are `code`, `customer_id`, `order_id`, `customer_email`, `id`, `used_on`, `updated_at`. When specified, the results are sorted in ascending order based on the value of the field. To sort in descending order, prefix the attribute with -, for example, -updated_at. The default sort order is updated_at in descending order. See [Sorting](/guides/Getting-Started/sorting). |

## Filtering 

The following operators and attributes are available for filtering usages:

| Attribute | Type | Operators | Example  |
| ---------| --------- | ---------------------------| -------- |
| `id` | `string` | `eq` | `eq(id,8dac76b3-9282-4730-b1dd-bdd2a95610cb)` |
| `code` | `string` | `eq` | `eq(code,cart1off)` | 
| `used_on` | `string` | `gt`,`ge`,`le` and `lt` | `gt(used_on,2023-07-11)` |

## Request Example

```bash
curl https://useast.api.elasticpath.com/v2/promotions/:id/usages \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "id": "a042bd4b-21a6-4f55-8add-5a3e8b862ddc",
            "order_id": "01e2a292-f92e-4579-973c-2f3bc70acec1",
            "code_id": "7905c48a-55b0-4bf0-abd7-c2cdbbb944e9",
            "code": "cart2uses",
            "times_used": 1,
            "used_on": "2023-05-30T23:10:56.016Z",
            "customer_id" : "1eaf092c-f6e1-48e6-a64f-1c092b711916",
            "customer_email": "test@email.com",
            "meta": {
                "timestamps": {
                    "updated_at": "2024-01-03T17:37:47.111Z"
                }
            },
            "anonymized": false
        }
    ]
}
```

---

## Overview(Promotion-usages)

Promotion usages are helpful in tracking and understanding how promotional offers are utilized. This includes details such as which promotions were used, how frequently they were used, order ID, code ID, customer email, date of the promotion's usage. To retrieve the usage history of a specific promotion, see [Get Promotion Usages](/docs/api/promotions/get-promotion-codes).

You can also track the history of a specific promotion code within a particular promotion. See [Get a Promotion Code Usage](/docs/promotions/promotion-usages/get-a-promotion-code-usage).

Additionally, you can also choose to anonymize customer email addresses associated with promotion usages. For more information, see [Anonymize Usages](/docs/promotions/promotion-usages/anonymize-usages).

---

## Promotions Standard vs Promotions Builder

Promotions Builder is the next generation of Promotions Standard, offering enhanced functionality and flexibility. Below is a comparison of current features between the two. This comparison will be regularly updated as new capabilities become available in Promotions Builder.

We recommend the use of Promotions Builder for all new promotions.

## Feature Comparison

### Promotion Types

| Feature                                                   | Promotions Standard | Promotions Builder |
|-----------------------------------------------------------|---------------------|--------------------|
| Fixed Price Promotions (products, categories, attributes) | ⚠️¹                 | ✅                  |
| Discounts (All/Cheapest/Most Expensive Eligible Items)    | ⛔️                  | ✅                  |
| Discounts for Specific Item Quantities                    | ⚠️²                 | ✅                  |
| Maximum Discount                                          | ✅                   | ✅                  |
| Bundle Discounts                                          | ⚠️                  | ✅                  |
| Buy X Get Y                                               | ⛔️                  | ✅                  |
| Buy X for Y (buy in multiples of)                         | ✅                   | 🕒                 |
| Free Gift with Auto-Add                                   | ✅                   | ✅                 |
| Promotion Carrots for Products                            | ⛔️                  | ✅                  |
| Free Shipping Promotions (shipping groups)                | ⛔️                  | ✅                  |

### Promotion Conditions & Actions

| Feature                                                     | Promotions Standard | Promotions Builder |
|-------------------------------------------------------------|---------------------|--------------------|
| Promotions by Product SKU, Product ID,  Category, Attribute | ✅                   | ✅                  |
| Multiple Matching Criteria per Promotion                    | ⛔️                  | ✅                  |
| Multiple Discount Actions per Promotion                     | ⛔️                  | ✅                  |
| Conditional Operators (e.g., greater than or equal to)      | ⛔️                  | ✅                  |
| Conditions by Item Price (API only)                         | ⛔️                  | ✅                  |
| Cart Custom Attributes                                      | ⛔️                  | ✅                  |
| Promotions by Account Tags                                  | ⛔️                  | ✅                  |
| Cart Item Quantity Conditions (line item quantity)          | ⚠️²                 | 🕒                 |
| Item Quantity Conditions (Cart-wide minimum)                | ⛔️                  | 🕒                 |
| Maximum quantity limit (of the same SKU)                    | ✅                   | ✅                  |
| Maximum quantity limit across all eligible items            | ⛔                   | ✅                  |
| Targeting Sub-total                                         | ✅                   | ✅                  |
| Targeting Line Item Totals                                  | ⛔️                  | ⛔️                 |
| Advanced Exclusion Sub-Conditions                           | ✅                   | ✅                  |
| Advanced Inclusion Sub-Conditions                           | ⛔️                  | ✅                  |
| Cart item custom attributes                                 | ⛔️                  | ✅                  |

### Coupon Management

| Feature                                 | Promotions Standard | Promotions Builder |
|-----------------------------------------|---------------------|--------------------|
| Bulk Coupon Code Generation (over 1000) | ✅                   | ✅                  |
| Coupon Code Quantity Limits             | ✅                   | ✅                  |
| Max Usage per Customer                  | ⛔️                  | ✅                  |
| First-Time Shopper Coupon Code          | ⛔️                  | ✅                  |
| Case Sensitive Coupon Codes             | ✅                   | ⛔️                 |
| One Coupon Code, Multiple Promotions    | ⛔️                  | ✅                  |
| Duplicate Promotion                     | ✅                   | ✅                  |

### Stacking & Priority

| Feature            | Promotions Standard | Promotions Builder |
|--------------------|---------------------|--------------------|
| Promotion Stacking | ⚠️³                 | ✅                  |
| Override Stacking  | ⛔️                  | ✅                  |
| Promotion Priority | ⛔️                  | ✅                  |

### Administration & Reporting

| Feature                           | Promotions Standard | Promotions Builder |
|-----------------------------------|---------------------|--------------------|
| Promotion History                 | ✅                   | 🕒                 |
| Advanced Search                   | ⛔️                  | ✅                  |
| Cart Promotion Preview (API only) | ✅                   | ✅                  |

¹ Applicable to same item only\
² Limited to bundle promotions only\
³ Only by creation date

**Legend:**\
✅ Supported | ⚠️ Limited Support | 🕒 Planned | ⛔️ Not Supported

## Related Resources

- [Promotions Builder in Commerce Manager](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder)
- [Promotions Builder API](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview)

---

## Overview(4)

The Promotions Builder helps users create various types of promotions based on customizable conditions and actions. Through flexible rules and strategies, the Promotions Builder allows merchants to build complex promotions tailored to specific business needs.

The Promotions Builder provides the flexibility to offer diverse discounts to shoppers. They support discounts of varying complexities, from code-based customer discounts, to Buy X Get Y scenarios, fixed price promotions, and more based on your business needs.

You can create a Promotion using the [Promotions Builder API](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview) or [Commerce Manager](/docs/commerce-manager/promotions-builder/index).

To apply Promotions Builder API in carts and orders, ensure that you have enabled the `use_rule_promotions` field in [Cart Settings](/docs/api/carts/put-v-2-settings-cart). You can also update a specific cart to use Promotions Builder. See [Update a Cart](/docs/api/carts/update-a-cart). This turns on hybrid mode, which means you can simultaneously use both [Promotions Standard](/docs/api/promotions/promotions-standard-introduction) and Promotions Builder. For example, let's consider the following scenario:

If the cart has:
- A Promotions Standard offering a 10% discount on the shopping cart
- A Promotions Builder offering a 20% discount on the shopping cart

    Shoppers qualify for both discounts, prompting the system to apply both types of discount to your shopping cart. This means you get a 10% discount from the Promotions Standard and a 20% discount from the Promotions Builder. The Promotions Standard discount is always applied before the Promotions Builder discount, regardless of their creation dates. After applying the Promotions Standard discount, the Promotions Builder discount is then applied based on its creation date, with the newest promotion applied first and the oldest promotion stacked on top of the newest promotion.

:::note

- Cart-level discounts that are checked out will appear on orders with the same type as they do in carts, labeled as `promotion_item`. For backward compatibility, this change is specific to Promotions Builder only.
- When managing promotions and discounts, multiple types of discounts use the same promotion code. The system breaks down these discounts in the cart item’s metadata. This breakdown is detailed in the `discounts.constituents` object, showing which part of the discount comes from which specific promotion, identified by their promotion ID. When you use the [Get Cart Items](/docs/api/carts/get-cart-items) endpoint, the response example shows the breakdown of the same promotion code used in both Promotions Standard and Promotions Builder.

:::

## Rule Set

A rule set is essentially a set of criteria that determine when and how a promotion should be applied. It consists of conditions and corresponding actions. It can also contain targeted catalogs and currencies.

### Conditions

Conditions describe the criteria necessary for discount eligibility. For example, *Buy X get Y 50% off*. This condition requires the shopper to buy one item to receive 50% discount on another item. For more information, see [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

### Actions

Actions describe how discounts are applied to eligible carts and orders. These signify the discount type, level, configuration, and any limitations or restrictions when applying.

You can create actions to specify:

- Action conditions: Specifying which items should be included or excluded when applying the discounts. This can be based on factors such as item SKUs, product attributes, quantities, categories. For more information, see [Create a Condition Promotion](/docs/promotions-builder/promotions-builder-api/item-level-promotions/create-item-discount-with-condition).
- Action limitations: Imposing restrictions or limitations on the number of products eligible for discounts, maximum discount amounts, and total applications for discounts. For more information, see [Action Limitations](/docs/promotions-builder/promotions-builder-api/action-limitations/action-limitations-overview).

### Sub Conditions

Sub conditions offer further refinement within rules and actions, specifying additional criteria that must be met for the promotion or discount to be applied. These can include conditions such as minimum quantities for specific item SKUs, exclusion of certain items, or additional constraints for eligibility. For more information, see [Create a Cart Percent Discount with Sub Conditions](/docs/promotions-builder/promotions-builder-api/cart-level-promotions/create-a-cart-percent-discount-with-subconditions) and [Create an Item Promotion with Sub Conditions](/docs/promotions-builder/promotions-builder-api/item-level-promotions/create-an-item-promotion-with-sub-conditions).

### Strategies

Strategies describe the type of condition or action.

For instance:
- Rule strategies define the types of conditions that need to be met for eligibility. These might include cart total amount, item prices, cart custom attributes, and more.
- Action strategies refer to the type of action execution run when the eligibility criteria are met. For actions, the possible strategies are `cart_discount` and `item_discount`. For more information, see [Promotions Builder API Overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

### Catalogs and Currencies

You can specify which catalogs and currencies the rules apply to. When catalogs are defined in a promotion, the promotion cannot apply to custom items. When no catalogs are defined, the promotion can apply to any item type, including custom items.

You can choose to apply discounts to carts in a specific currency. If no currencies are defined, the discount applies to carts in any currency.

You can only set one currency for each promotion.

## Logical Operators

Operators are used to determine when a promotion should be triggered. Different rule strategies support different operators. For more information, see [Promotions Builder API Overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Arguments

Arguments are the values associated with conditions and actions within a Promotions Builder. The accepted arguments for each strategy can vary, though they are all passed in the same form. In cases where the arguments are arrays, values within the arrays are OR'ed together.

Consider the following scenarios:

- Let's consider a condition where we want to target specific product categories.

    ```json
    {
      "strategy": "item_category",
      "operator": "in",
        "args": [
            "dog-balls",
            "chew-toys"
        ]
    }
    ```

    In this condition example, we are using the `item_category` strategy to target products based on their category. The `in` operator is used to specify that we want to include items that belong to certain categories.  The arguments are the specific categories we want to include. In this case it is `dog-balls` and `chew-toys`.

    This condition instructs the system to consider items that fall into either the `dog-balls` or `chew-toys` categories for eligibility.

- In an action, the arguments specify the details or configuration when applying a discount.

    ```json
    {
        "actions": [
            {
                "strategy": "cart_discount",
                "args": [
                    "percent",
                    10
                ]
            }
        ]
    }
    ```

    In this action example, the strategy is `cart_discount`, indicating that the action involves applying a discount to the cart.  The arguments specify that the discount should be applied as a percentage, taking 10% off. In this case, it is `"percent", 10`.

## Promotion Codes

You can generate codes for a Promotions Builder so that shoppers receive the discount when the code is provided. You can enable this feature by setting the `automatic` field to `false` in the promotions schema when you create a Promotions Builder. For more information, see [Create Promotion Codes](/docs/promotions-builder/promotions-builder-codes/create-promotion-codes). To create promotion codes in Commerce Manager, see [Creating Promotion Codes in Commerce Manager](/docs/commerce-manager/promotions-builder/creating-promotion-codes).

To learn more about promotion codes, see [Promotion Codes](/docs/promotions-builder/promotions-builder-codes/create-promotion-codes).

:::note
- The promotion codes are case-insensitive.
- Multiple promotions can have the same code name. This means that different promotions can be identified using the same code names, allowing shoppers to apply a single coupon code that triggers multiple promotions. For more information see [Duplicate Codes](/docs/promotions-builder/promotions-builder-codes/create-promotion-codes#duplicate-codes).
:::

### Promotion Usages

Promotion usages are helpful in tracking and understanding how promotional offers are utilized. This includes details such as which promotions were used, how frequently they were used, order ID, code ID, customer email, date of the promotion's usage. To retrieve the usage history of a specific promotion, see [Get Promotion Usages](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages).

You can also track the history of a specific promotion code within a particular promotion. See [Get a Promotion Code Usage](/docs/promotions-builder/promotions-builder-codes/get-a-promotion-code-usage).

Additionally, you can also choose to anonymize customer email addresses associated with promotion usages. For more information, see [Anonymizing Promotion Code Usages](/docs/promotions-builder/promotions-builder-codes/Anonymize-promotion-code-usages).

## Cart-level Discount Apportioning

Discount apportioning involves distributing cart-level discounts among the individual items in the cart, ensuring transparency and clarity in how discounts are allocated and represented at both the cart and item levels. Each discount includes essential details such as IDs, codes, amounts, and indicates their source as `rule-promotion`. It is important to note that item-level apportioning for cart-level discounts specifically applies to Promotions Builder.

Even if an apportioned amount amounts to zero, it is distributed among all items for consistency. Apportioned item-level discounts include a flag, such as `is_cart_discount`, to easily identify them as originating from cart-level promotions, aiding API consumers in reconciliation. This flag is used to check if the discount applied to cart item is from cart discount.

:::note
- The new discount apportioning algorithm ensures accuracy and consistency in the `item.discounts` and `item.meta.display_price.discounts` fields. However, slight differences may occur in the `item.meta.display_price.discount` fields due to intricacies in partial-amount rounding. It is important to consider the `item.discounts` and `item.meta.display_price.discounts` as the accurate representations of discount values.
- Apportioning for uneven values may reflect differently between a cart’s items and its corresponding order items post-checkout. Although the distribution of discounts may vary slightly between the cart and the order, the fundamental calculations and total discount amounts remain the same.
- The cart total will be calculated based on the discount values apportioned to individual items.
:::

Consider the following scenario:
- Create a [cart fixed discount promotion](/docs/promotions-builder/promotions-builder-api/cart-level-promotions/create-a-cart-fixed-discount), with a cart discount of $10. When a cart with eligible items, SKU1 and SKU2, with a price of $100 each, applies this cart discount, the system accurately distributes the discount among the items based on their proportions to the overall cart total.
- In this case, SKU1 and SKU2 with a price of $100 each, receive an apportioned discount of $5.00. Both items display the apportioned discount details in the `discounts` array in the response, along with the `is_cart_discount` flag indicating it's a cart-level discount. Upon checkout, the order items also reflect the apportioned discount details, ensuring transparency and accuracy in discount allocation.

See the following response example:

```json
{
    "data": [
        {
            "id": "832b6901-6943-43dd-b59d-273667500cad",
            "type": "custom_item",
            "name": "item",
            "description": "custom item",
            "sku": "SKU101",
            "slug": "",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "discounts": [
                {
                    "amount": {
                        "amount": -500,
                        "currency": "USD",
                        "includes_tax": false
                    },
                    "code": "auto_b0dbd44d-e361-4388-acaa-aec40990e86f",
                    "id": "b0dbd44d-e361-4388-acaa-aec40990e86f",
                    "promotion_source": "rule-promotion",
                    "is_cart_discount": true
                }
            ],
            "links": {},
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 9500,
                            "currency": "USD",
                            "formatted": "$95.00"
                        },
                        "value": {
                            "amount": 9500,
                            "currency": "USD",
                            "formatted": "$95.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 9500,
                            "currency": "USD",
                            "formatted": "$95.00"
                        },
                        "value": {
                            "amount": 9500,
                            "currency": "USD",
                            "formatted": "$95.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        },
                        "value": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    },
                    "discounts": {
                        "auto_b0dbd44d-e361-4388-acaa-aec40990e86f": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-04-30T19:12:04Z",
                    "updated_at": "2024-04-30T19:12:04Z"
                }
            }
        },
        {
            "id": "9bec80e8-6c48-4d5d-800d-8507ed68e5dc",
            "type": "promotion_item",
            "promotion_id": "b0dbd44d-e361-4388-acaa-aec40990e86f",
            "name": "$10 off carts >= $100",
            "description": "Promotion",
            "sku": "auto_b0dbd44d-e361-4388-acaa-aec40990e86f",
            "slug": "",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": -1000,
                "currency": "USD",
                "includes_tax": false
            },
            "links": {},
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "value": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        },
                        "value": {
                            "amount": -1000,
                            "currency": "USD",
                            "formatted": "-$10.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 0,
                            "currency": "",
                            "formatted": "0"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "",
                            "formatted": "0"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-04-30T19:12:04Z",
                    "updated_at": "2024-04-30T19:12:09Z"
                }
            },
            "promotion_source": "rule-promotion"
        },
        {
            "id": "a4a27cb4-7eb4-4d10-ac0c-98416a0051ad",
            "type": "custom_item",
            "name": "item",
            "description": "custom item",
            "sku": "SKU100",
            "slug": "",
            "image": {
                "mime_type": "",
                "file_name": "",
                "href": ""
            },
            "quantity": 1,
            "manage_stock": false,
            "unit_price": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "value": {
                "amount": 10000,
                "currency": "USD",
                "includes_tax": false
            },
            "discounts": [
                {
                    "amount": {
                        "amount": -500,
                        "currency": "USD",
                        "includes_tax": false
                    },
                    "code": "auto_b0dbd44d-e361-4388-acaa-aec40990e86f",
                    "id": "b0dbd44d-e361-4388-acaa-aec40990e86f",
                    "promotion_source": "rule-promotion",
                    "is_cart_discount": true
                }
            ],
            "links": {},
            "meta": {
                "display_price": {
                    "with_tax": {
                        "unit": {
                            "amount": 9500,
                            "currency": "USD",
                            "formatted": "$95.00"
                        },
                        "value": {
                            "amount": 9500,
                            "currency": "USD",
                            "formatted": "$95.00"
                        }
                    },
                    "without_tax": {
                        "unit": {
                            "amount": 9500,
                            "currency": "USD",
                            "formatted": "$95.00"
                        },
                        "value": {
                            "amount": 9500,
                            "currency": "USD",
                            "formatted": "$95.00"
                        }
                    },
                    "tax": {
                        "unit": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        },
                        "value": {
                            "amount": 0,
                            "currency": "USD",
                            "formatted": "$0.00"
                        }
                    },
                    "discount": {
                        "unit": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        },
                        "value": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        }
                    },
                    "without_discount": {
                        "unit": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        },
                        "value": {
                            "amount": 10000,
                            "currency": "USD",
                            "formatted": "$100.00"
                        }
                    },
                    "discounts": {
                        "auto_b0dbd44d-e361-4388-acaa-aec40990e86f": {
                            "amount": -500,
                            "currency": "USD",
                            "formatted": "-$5.00"
                        }
                    }
                },
                "timestamps": {
                    "created_at": "2024-04-30T19:12:09Z",
                    "updated_at": "2024-04-30T19:12:09Z"
                }
            }
        }
    ],
    "meta": {
        "display_price": {
            "with_tax": {
                "amount": 19000,
                "currency": "USD",
                "formatted": "$190.00"
            },
            "without_tax": {
                "amount": 19000,
                "currency": "USD",
                "formatted": "$190.00"
            },
            "tax": {
                "amount": 0,
                "currency": "USD",
                "formatted": "$0.00"
            },
            "discount": {
                "amount": -1000,
                "currency": "USD",
                "formatted": "-$10.00"
            },
            "without_discount": {
                "amount": 20000,
                "currency": "USD",
                "formatted": "$200.00"
            },
            "shipping": {
                "amount": 0,
                "currency": "USD",
                "formatted": "$0.00"
            }
        },
        "timestamps": {
            "created_at": "2024-04-25T00:34:48Z",
            "updated_at": "2024-04-30T19:12:09Z",
            "expires_at": "2024-05-07T19:12:09Z"
        },
        "messages": [
            {
                "source": {
                    "type": "custom_item",
                    "id": "832b6901-6943-43dd-b59d-273667500cad"
                },
                "title": "Discount Updated",
                "description": "Item discount has been updated."
            },
            {
                "source": {
                    "type": "custom_item",
                    "id": "a4a27cb4-7eb4-4d10-ac0c-98416a0051ad"
                },
                "title": "Discount Added",
                "description": "Item discount has been added."
            }
        ]
    }
}
```

## Condensed Promotion

A condensed promotion is essentially an object that contains specific meta information about a promotion applied to the cart or order.

Condensed promotions can be retrieved from the following endpoints:

 - [Get a Cart](/docs/carts-orders/Includes#get-retrieve-promotions-from-a-cart): This endpoint displays cart-level condensed promotions within the included object. If `?include=items` is specified, the included object also contains cart item-level promotions. The relationships field at the cart level has a promotions section only when `?include=promotions` is specified.
 - [Get Cart Items](/docs/carts-orders/Includes#get-retrieve-promotions-from-cart-items): This endpoint shows both cart-level and item-level discounts in a condensed format within the included object.
 - [Get an Order](/docs/carts-orders/Includes#get-retrieve-promotions-from-an-order): This endpoint displays order-level condensed promotions within the included object.
 - [Get Order items](/docs/carts-orders/Includes#get-retrieve-promotions-from-order-items): This endpoint displays both order-level and item-level promotions in the included object.

This applies to both [Promotions Standard](/docs/api/promotions/promotions-standard-introduction) and Promotions Builder.

## Handling both Item SKU and Product ID together

Sometimes, a promotion condition needs to target items with or without a SKU (e.g., SKULess bundle items). To target SKULess items, we use the Product ID. However, a single array of arguments cannot contain both SKU and Product ID values simultaneously (e.g., ["sku1", "productID"]).

To address this, the `item_identifier` strategy allows merchandisers to set conditions based on either SKU or Product ID.

For example, the following condition checks if a cart item matches the SKU value defined in `skus` or matches the Product ID defined in `ids`.

```
{
    "strategy": "item_identifier",
    "operator": "in",
    "args": [
        {
            "skus": [
                "sku1"
            ],
            "ids": [
                "44d8077f-8fa3-4780-9df5-91d052be583f"
            ]
        }
    ]
}
```
The `nin` operator can also be used to exclude items based on categories or attributes. For example, the following condition requires items to belong to a specific category while excluding those with SKU `sku1` or Product ID `44d8077f-8fa3-4780-9df5-91d052be583f`.

This provides merchandisers with greater flexibility in filtering eligible items for promotions.

```
{
    "strategy": "item_category",
    "operator": "in",
    "args": [
        "667d9fae-d8c7-4941-b556-70cb4b8612f1"
    ],
    "children": [
        {
            "strategy": "item_identifier",
            "operator": "nin",
            "args": [
                {
                    "skus": [
                        "sku1"
                    ],
                    "ids": [
                        "44d8077f-8fa3-4780-9df5-91d052be583f"
                    ]
                }
            ]
        }
    ]
}
```
The strategy `item_identifier` can also be used in `actions` condition to narrow down the targeted items for discounts.

```
{
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        50
                    ],
                    "condition": {
                        "strategy": "item_category",
                        "operator": "in",
                        "args": [
                            "667d9fae-d8c7-4941-b556-70cb4b8612f1"
                        ],
                        "children": [
                            {
                                "strategy": "item_identifier",
                                "operator": "nin",
                                "args": [
                                    {
                                        "skus": [
                                            "nike_running1"
                                        ],
                                        "ids": [
                                            "44d8077f-8fa3-4780-9df5-91d052be583f"
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
}
```

See the API examples in [Create a Rule Promotion](/docs/api/promotions-builder/create-rule-promotion).

NOTE: All promotions using the old way of handling `item_sku` or `item_product_id` are still supported. For example:

```
"rules": {
                "strategy": "and",
                "children": [
                    {
                        "strategy": "or",
                        "children": [
                            {
                                "strategy": "item_sku",
                                "operator": "in",
                                "args": [
                                    "sku1",
                                    "sku2"
                                ]
                            },
                            {
                                "strategy": "item_product_id",
                                "operator": "in",
                                "args": [
                                    "44d8077f-8fa3-4780-9df5-91d052be583f"
                                ]
                            }
                        ]
                    },
                    {
                        "strategy": "item_quantity",
                        "operator": "gte",
                        "args": [
                            1
                        ]
                    }
                ]
            },
```
However, the `item_identifier` strategy is recommended due to simplicity.

## Promotion Stacking and Priority

Stacking and Priority are essential concepts in managing promotions, ensuring that promotions are applied effectively and as intended.

**Promotion Stacking** refers to the ability to stack multiple promotions on a single cart, it is possible to target the same items with multiple promotions or completely different items. A priority can be set to determine which promotions are applied first. If no priority is set, the promotions apply in order of creation date, with the newest promotions applied first and discounted prices calculated against any previously-discounted item prices. When promotions are stackable, they can be applied simultaneously, allowing shoppers to benefit from multiple discounts. The `stackable` flag in the promotion settings determines whether a promotion can be stacked with others. By default, this flag is set to `true`, enabling stacking. If the flag is set to `false`, no other promotion can stack on top. The promotion with the highest priority will take precedence. For more details, refer to the [Stacking Promotion Scenarios](/docs/promotions-builder/overview/#stacking-promotion-scenarios) to understand the effects on stackable and non-stackable promotions.

**Promotion Priority** refers to the order in which promotions are applied and calculated in the cart. This is managed using the `priority` setting while creating a promotion. Priorities are represented as integers, with higher numbers indicating higher priority. Setting a priority for promotions is optional; by default, promotions do not have a priority value. If there is no priority set, the most recently created promotion will be applied first. When `priority` is set, each promotion must have a unique priority value. This ensures that when multiple promotions are eligible, the one with the highest priority is applied first, followed by the next highest. If a non-stackable promotion has the highest priority, it will be the only promotion that applies.

**For example**, Promotion A (priority 90) and Promotion B (priority 80) are both non-stackable. If Promotion B is applied and then Promotion A becomes eligible, Promotion A will replace Promotion B in the cart.

When promotions are stackable, they can be stacked on a cart. The order is determined first by priority and then by the creation date. **For example**, Promotion E (priority 70) and Promotion F (priority 60) are both stackable. Both promotions will be applied, with Promotion E being applied first due to its higher priority.

If Hybrid Mode is enabled, Promotions Standard and Promotions Builder features will coexist for the given store. In these cases, the Promotions Standard and Promotions Builder features function independently on the same cart. For example, Standard Promotions will still apply even if promotions configured in Promotions Builder are non-stackable.  Similarly, the stackability and priority configurations for promotions created with the Promotions Builder will not impact Standard Promotions.

Standard Promotions can be applied alongside promotions configured in the Promotions Builder. They can coexist with non-stackable Promotions configured in the Promotions Builder. The stackability and priority settings in the Promotions Builder don't impact the application of Standard Promotions.

When both an item discount and a cart discount are non-stackable, only the higher priority or the newer one will be applied to the cart.

See [how to create a promotion with stackable and priority flags](/docs/promotions-builder/promotions-builder-api/cart-level-promotions/create-a-cart-fixed-discount#request-example---priority-and-stackable-flags).

### Stacking Promotion Scenarios

#### Scenario 1: Only one higher priority non-stackable promotion is applied

Consider you have the following promotions:

- Promotion A: Priority 90, Non-Stackable, with coupon code `big-flash-sale`.
- Promotion B: Priority 60, Non-Stackable, with coupon code `monthly-special`.

If Promotion A is applied first and the shopper attempts to apply Promotion B, Promotion B will not be applied.

The following error message is returned:

```json
"messages": [
            {
                "source": {
                    "type": "promotion",
                    "id": "50b49554-60d7-4ddc-b18b-0f2a7d1781c3",
                    "code": "monthly-special"
                },
                "title": "Couldn't Stack Promotion",
                "description": "Non-stackable promotion can't be applied with non-stackable promotion."
            }
        ]
```

#### Scenario 2: Higher Priority non-stackable promotion removes lower priority Promotion

Consider you have the following promotions:

- Promotion B: Priority 90, Non-Stackable
- Promotion E: Priority 60, Non-Stackable

If Promotion E is applied first and the cart becomes eligible for Promotion B, Promotion B is applied and Promotion E is removed.

The following messages are returned in the cart response:

```json
"messages": [
            {
                "source": {
                    "type": "promotion_item",
                    "id": "660883ba-01d5-4f43-a791-df4151e0d0b3"
                },
                "title": "Promotion Added",
                "description": "Promotion has been added to cart."
            },
            {
                "source": {
                    "type": "promotion_item",
                    "id": "20b475c2-cfb9-4472-9fa1-e70c91dcbf3a"
                },
                "title": "Deleted Promotion",
                "description": "Promotion has been removed from cart."
            },
            {
                "source": {
                    "type": "promotion",
                    "id": "50b49554-60d7-4ddc-b18b-0f2a7d1781c3",
                    "code": "90"
                },
                "title": "Couldn't Stack Promotion",
                "description": "Non-stackable promotion can't be applied with non-stackable promotion."
            },
            {
                "source": {
                    "type": "cart_item",
                    "id": "1e1ed778-d3f3-45ea-9095-ffc8afffd0ae"
                },
                "title": "Discount Added",
                "description": "Item discount has been added."
            },
            {
                "source": {
                    "type": "cart_item",
                    "id": "1e1ed778-d3f3-45ea-9095-ffc8afffd0ae"
                },
                "title": "Discount Deleted",
                "description": "Item discount has been removed."
            }
        ]
```

#### Scenario 3: Higher priority promotion takes precedence when mixing stackable and non-stackable Promotions

Consider you have the following Promotions:

- Promotion A: Priority 100, Stackable
- Promotion B: Priority 90, Non-Stackable

If Promotion B is applied first (non-stackable) and the shopper applies Promotion A, Promotion A is applied because it has a higher priority. Therefore, Promotion B will be removed from the cart.

The following messages indicating the removal of Promotion B and the application of Promotion A are returned:

```json
"messages": [
            {
                "source": {
                    "type": "promotion_item",
                    "id": "860a5a24-cce1-4241-84c1-53f54a7237ce"
                },
                "title": "Promotion Added",
                "description": "Promotion has been added to cart."
            },
            {
                "source": {
                    "type": "promotion_item",
                    "id": "884357f0-83b8-4d5d-8e0b-4c845345033d"
                },
                "title": "Deleted Promotion",
                "description": "Promotion has been removed from cart."
            },
            {
                "source": {
                    "type": "promotion",
                    "id": "50b49554-60d7-4ddc-b18b-0f2a7d1781c3",
                    "code": "90"
                },
                "title": "Couldn't Stack Promotion",
                "description": "Non-stackable promotion can't be applied with stackable promotions."
            },
            {
                "source": {
                    "type": "cart_item",
                    "id": "7547f703-f8d6-44e4-ba0c-94bf505d0659"
                },
                "title": "Discount Added",
                "description": "Item discount has been added."
            },
            {
                "source": {
                    "type": "cart_item",
                    "id": "7547f703-f8d6-44e4-ba0c-94bf505d0659"
                },
                "title": "Discount Deleted",
                "description": "Item discount has been removed."
            }
        ]
```

#### Scenario 4: Higher priority promotion takes precedence when applying multiple stackable promotions

When multiple promotions are stackable and have different priority levels, the promotion with the highest priority is applied first, followed by other promotions in descending order of priority.

For example, consider two stackable promotions:

- Promotion A: Priority 90, discount 20%
- Promotion B: Priority 60, discount 10%

In this scenario, Promotion A, with a higher priority of 90, is applied first, providing a 20% discount. Promotion B, with a priority of 60, is then applied, offering an additional 10% discount on the already reduced price.

Now, consider an item with an original price of $100. The price after applying Promotion A (20% discount) would be $80.00, and the price after applying Promotion B (10% discount) would be $72.00.

## Override Stacking
Override stacking enables a promotion to be stacked on otherwise non-stackable promotions. This enables you to create promotions that will always stack, even if the first applied promotion is non-stackable.
An example use case is offering free shipping on all orders during a sale. You can set up a free shipping promotion with override_stacking set to true. This ensures that the free shipping promotion will always apply, regardless of other promotion types, without needing to modify existing promotions.
The order in which promotions stack depends on their **Priority**. The promotion with the highest **Priority** value takes precedence.

Simply set the `stackable` and `override_stacking` values to `true` or `false` when creating the promotion to control how it stacks with other promotions.

When applying eligible promotions, the following rules govern stacking and application behavior:
- Stackable, non-override --> apply unless a non-stackable promotion was already applied
- Stackable, override --> apply unless a non-stackable, override promotion was already applied
- Non-stackable, non-override --> apply only if this is the first promotion (i.e., no other promotions applied yet)
- Non-stackable, override --> apply unless a stackable, override promotion was already applied

Here are some possible scenarios and behaviors:

### Case 1: Override_stacking promotion stacks on top of non-stackable promotion.

| promotion       | priority | stackable | override_stacking |
|:----------------|:---------|:----------|:------------------|
| PromoA          | 100      | false     | false             |
| PromoB          | 90       | true      | true              |

Result:
PromoA applies first, then PromoB stacks on top of PromoA.

### Case 2: Override_stacking promotion stacks on another override_stacking promotion.

| promotion       | priority | stackable | override_stacking |
|:----------------|:---------|:----------|:------------------|
| PromoA          | 100      | false     | false             |
| PromoB          | 90       | true      | true              |
| PromoC          | 80       | true      | true              |

Result:
PromoA applies first, then followed by PromoB and PromoC based on priority.

### Case 3: Override_stacking promotion cannot stack on another non-stackable override_stacking promotion

| promotion       | priority | stackable | override_stacking |
|:----------------|:---------|:----------|:------------------|
| PromoA          | 100      | false     | false             |
| PromoB          | 90       | false     | true              |
| PromoC          | 80       | true      | true              |

Result:
PromoA applies to the cart based on highest priority. PromoB stacks on top of PromoA since it has the override_stacking. PromoC cannot stack because PromoB is non-stackable.

## Related Resources

- [Promotions Builder in Commerce Manager](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder)
- [Promotions Builder API](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview)

---

## Overview(Action-limitations)

Action limitations refer to restrictions or limitations that can be applied to promotions. These limitations dictate how the promotion can be used and what criteria must be met for it to be applied. 

They can be combined with action conditions to create specific rules for the promotion. For more information, see [Create an Item Fixed Discount with Condition Rule Promotion](/docs/promotions-builder/promotions-builder-api/item-level-promotions/create-item-discount-with-condition/).

The following are the limitations that are applied to promotions:

- Maximum Discount: This limitation sets the total discount amount that can be applied to the promotion. This limitation applies to Cart Percent and Item percent discount promotions.
- Maximum Quantity: This limitation ensures the promotion is limited to a specific quantity of the same items. This limitation applies to Item discount promotions.
- Items: This limitation applies only to Item fixed and Item Percent discount promotions. It restricts the total number of items in the cart that are eligible for the promotion. It is applied based on a price strategy, such as `cheapest` or `expensive`. By default, price strategy is `cheapest`. You can also combine this with other limitations like `max_discount` and `max_quantity`.
     - Cheapest: This limitation ensures that the promotion is applied to the cheapest item or items in the cart.
     - Expensive: This limitation applies the promotion to the most expensive items in the cart.

These limitations can be combined and applied separately according to your business requirements. See [Create Action Limitations](/docs/promotions-builder/promotions-builder-api/action-limitations/create-limitations-and-exclusion-rule-promotion/).

---

## Create Action Limitations and Exclusions Promotion

## `POST` Create Action Limitations and Exclusions Promotion

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Body

For descriptions of other fields such as `type`, `name`, `description`, `enabled`, `automatic`, `start`, `end`, `rule_set`, and `actions.strategy` refer to [Rules Promotion API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-management/get-promotions/).

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `action.limitations.max_discount` | Optional | `integer` | Specifies the maximum amount of discount applied to the shopping cart. For example, for a cart percent discount, you can set a maximum of $50 discount for a cart with a 50% discount. For item percent discount promotion, each item can be discounted by 20% with a maximum discount limitation of $10. |
| `action.limitations.max_quantity` | Optional | `integer` | Specifies the maximum quantity of each eligible item to which the promotion is applied. For example, if `max_quantity` is set to two, only two units of SKU1 can receive the discount. | 
| `action.limitations.items.max_items` | Required if defining items limitations. | `integer` | Specifies the maximum number of items eligible for the discount. For example, in a promotion offering 50% off eligible items within a category, if the maximum number of items is set to five, only up to 5 items from that category receive the discount. |
| `actions.limitations.items.price_strategy` | Optional | `string` | Specifies the strategy for determining which items to discount based on their individual prices. The available options are `cheapest` and `expensive`. When set to `cheapest`, the discount is applied to the cheapest items in the cart. When set to `expensive`, the discount is applied to the most expensive items in the cart. If neither `cheapest` nor `expensive` is chosen, the discount applies to all eligible items. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "50% max $10 max 2 items 2 quantities from category",
        "description": "Items from category 50% off max $10 off 2 cheapest items with max quantity of 2 excluding one item",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-01",
        "end": "2050-01-01",
        "rule_set": {
            "rules": {
                "strategy": "and",
                "children": [
          {
                    "strategy": "item_category",
                    "operator": "in",
                    "args": [
                        "e3807d4d-010e-494c-8227-9a5cfd8f1177"
                    ]
          },
          {
                    "strategy": "item_sku",
                    "operator": "nin",
                    "args": [
                        "exclude_item_sku"
            ]
          }
        ]
      },
            "actions": [
        {
                "strategy": "item_discount",
                "args": [
                    "percent",
                    50
          ],
                "limitations": {
                    "max_quantity": 2,
                    "max_discount": 1000,
                    "items": {
                        "max_items": 2,
                        "price_strategy": "cheapest"
            }
          }
        }
      ]
    }
  }
}      
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "81ffcf93-c090-49c8-9d74-893057fc9ad3",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "50% max $10 max 2 items 2 quantities from category",
        "description": "Items from category 50% off max $10 off 2 cheapest items with max quantity of 2 excluding one item",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "catalog_ids": null,
            "currencies": null,
            "rules": {
                "strategy": "and",
                "operator": "",
                "args": null,
                "children": [
                    {
                        "strategy": "item_category",
                        "operator": "in",
                        "args": [
                            "e3807d4d-010e-494c-8227-9a5cfd8f1177"
                        ]
                    },
                    {
                        "strategy": "item_sku",
                        "operator": "nin",
                        "args": [
                            "exclude_item_sku"
                        ]
                    }
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        50
                    ],
                    "limitations": {
                        "max_discount": 1000,
                        "max_quantity": 2,
                        "items": {
                            "max_items": 2,
                            "price_strategy": "cheapest"
                        }
                    }
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-03-12T20:44:20.681Z",
                "updated_at": "2024-03-12T20:44:20.681Z"
            }
        }
    }
}
```

---

## Create a Cart Fixed Discount

## `POST` Create a Cart Fixed Discount

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "$5 off cart when cart is $100 or more",
        "description": "cart rule $5 off your order!",
        "enabled": true,
        "automatic": true,
        "start": "2023-12-01",
        "end": "2024-01-01",
        "rule_set": {
            "catalog_ids":["09b9359f-897f-407f-89a2-702e167fe781"],
            "currencies":["CAD"],
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [10000]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": ["fixed", 500]
                }
            ]
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "d9b7f262-c1dd-4765-8987-4d712164d8f6",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "$5 off cart when cart is $100 or more",
        "description": "cart rule $5 off your order!",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "catalog_ids": [
                "09b9359f-897f-407f-89a2-702e167fe781"
            ],
            "currencies": [
                "CAD"
            ],
        "rule": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    10000
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "fixed",
                        500
                    ]
                }
            ]
        },
        "start": "2023-12-01T00:00:00Z",
        "end": "2024-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2023-12-20T17:41:50.284Z",
                "updated_at": "2023-12-20T17:41:50.284Z"
            }
        }
    }
}
```

## Request Example - Priority and Stackable Flags

The following request example shows how to create a rule promotion with `priority` and `stackable` flags:

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "promo with priority 100",
        "description": "promo with priority 100",
        "enabled": false,
        "automatic": false,
        "priority": 100,
        "stackable": true,
        "start": "2023-12-01",
        "end": "2024-01-01",
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [10000]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": ["fixed", 500]
                }
            ]
        }
    }
}
```

## Response Example - Priority and Stackable Flags

The following response example shows the `priority` and `stackable` values:

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "422d4cff-3069-4ec2-9d04-410db05444e3",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "promo with priority 100",
        "description": "promo with priority 100",
        "enabled": false,
        "automatic": false,
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    10000
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "fixed",
                        500
                    ]
                }
            ]
        },
        "start": "2023-12-01T00:00:00Z",
        "end": "2024-12-31T00:00:00Z",
        "stackable": true,
        "priority": 100,
        "meta": {
            "timestamps": {
                "created_at": "2024-07-09T17:03:04.211Z",
                "updated_at": "2024-07-09T17:03:04.211Z"
            }
        }
    }
}
```

The following error message is returned when you attempt to create a rule promotion with a `priority` that is already in use by another promotion:

```json
{
    "errors": [
        {
            "status": "422",
            "title": "Duplicate priority",
            "detail": "Priority already in use in another running or scheduled promotion"
        }
    ]
}
```

---

## Create a Cart Percent Discount

## `POST` Create a Cart Percent Discount

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/overview).

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "10% off cart rule",
        "description": "cart rule 10% off your order!",
        "enabled": false,
        "automatic": false,
        "start": "2024-01-01",
        "end": "2025-01-01",
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [100]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": ["percent", 20]
                }
            ]
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "009527e4-1cb4-40c7-9da4-8cd2aed864cf",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "10% off cart rule",
        "description": "cart rule 10% off your order!",
        "enabled": false,
        "automatic": false,
        "rule": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    100
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        20
                    ]
                }
            ]
        },
        "start": "2024-01-01T00:00:00Z",
        "end": "2025-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2023-12-18T22:12:36.276Z",
                "updated_at": "2023-12-18T22:12:36.276Z"
            }
        }
    }
}
```

---

## Create a Cart Percent Discount with Sub Conditions

## `POST` Create a Cart Percent Discount with Sub Conditions

Sub conditions refer to additional criteria or conditions that must be met for a particular promotion to be applied.

The `cart_total` strategy now supports the inclusion of sub conditions, allowing for more granular control over when promotions or actions associated with this strategy should be applied based on the contents of the cart. 

For promotions applied at the cart level, strategies applied are:

- `item_quantity`
- `item_category`
- `item_attribute`
- `item_sku`
- `item_product_id`

When multiple sub conditions exist, they function as `and` conditions, requiring all sub conditions to be fulfilled for the promotion to be applied.

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

In the following request example, sub conditions for the cart are specified within the `rule_set.rules.children` and `rule_set.actions.condition` objects.

For Rules (`rule_set.rules.children`): The sub condition specifies that items with the *exclusiveItem* SKU are excluded from the promotion when evaluating the cart's total value ("strategy": "cart_total").

For Actions (`rule_set.actions.condition`): The sub condition ensures that the 50% discount is applied only to items that do not have the SKU *exclusiveItem* SKU.

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "50 percent off cart excluding exclusive item",
        "description": "50 percent off your order excluding exclusive item",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-01",
        "end": "2050-01-01",
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    10000
                ],
            "children": [
            {
                "strategy": "item_sku",
                "operator": "nin",
                "args": [
                "exclusiveItem"
                ]
            }
            ]
        },
            "actions": [
            {
                "strategy": "cart_discount",
                "args": [
                    "percent",
                        50
                    ],
                "condition": {
                    "strategy": "item_sku",
                    "operator": "nin",
                        "args": [
                            "exclusiveItem"
                ]
          }
        }
      ]
    }
  }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "32e00eac-aae5-4384-95fb-ae606356dfc5",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "50 percent off cart excluding exclusive item",
        "description": "50 percent off your order excluding exclusive item",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    10000
                ],
                "children": [
                    {
                        "strategy": "item_sku",
                        "operator": "nin",
                        "args": [
                            "exclusiveItem"
                        ]
                    }
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        50
                    ],
                    "condition": {
                        "strategy": "item_sku",
                        "operator": "nin",
                        "args": [
                            "exclusiveItem"
                        ]
                    }
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-05-13T18:05:14.087Z",
                "updated_at": "2024-05-13T18:05:14.087Z"
            }
        }
    }
}
```

---

## Create a Cart Percent Discount with Account Tags

## `POST` Create a Cart Percent with Account Tags

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the other fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `rule_set.rules.strategy` | Required | `string`| The value for creating an Account Tags rule promotion is `account_tags`. |
| `rule_set.rules.operator` |  Required | `string`| The supported operators are `contains_all` and `contains_any`. |
| `rule_set.rules.args` |  Required | `string`| The list of account tag IDs used to determine eligibility.|

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
     "data": {
        "type": "rule_promotion",
        "name": "50 percent off cart with account tags",
        "description": "50 percent off cart with account tags",
        "enabled": true,
        "automatic": true,
        "start": "2024-01-01",
        "end": "2024-01-26",
        "rule_set": {
            "rules": {
                "strategy": "account_tags",
                "operator": "contains_all",
                "args": [
                    "3fa12770-cdf5-4168-a893-9a29eb1b43cc",
                    "31d60110-d492-4f93-983a-7cc466f12c54"
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        50
                    ]
                }
            ]
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "e42ec2df-5682-4047-bc22-9e5eb932ca4a",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "50 percent off cart with account tags",
        "description": "50 percent off cart with account tags",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "catalog_ids": null,
            "currencies": null,
            "rules": {
                "strategy": "account_tags",
                "operator": "contains_all",
                "args": [
                    "3fa12770-cdf5-4168-a893-9a29eb1b43cc",
                    "31d60110-d492-4f93-983a-7cc466f12c54"
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        50
                    ]
                }
            ]
        },
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-26T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-01-24T21:27:13.1Z",
                "updated_at": "2024-01-24T21:27:13.1Z"
            }
        }
    }
}
```

---

## Create a Cart Percent Discount with Custom Attribute

## `POST` Create a Cart Percent with Custom Attribute

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the other fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `rule_set.rules.strategy` | Required | `string`| Specifies the strategy for the rule. The supported strategy is `cart_custom_attribute`. |
| `rule_set.rules.operator` |  Required | `string`| Specifies the operators used for the rule strategy. The supported operators are `in` and `nin`. |
| `rule_set.rules.args` |  Required | `string`| Represents the condition value associated with each rule within the rule set. It requires at least three arguments.The first argument is the custom attribute key, a string of alphanumeric characters, underscores, or hyphens with a length between 1 to 255 characters. For example, `member_status`. See [Request Example](/docs/promotions-builder/promotions-builder-api/cart-level-promotions/create-a-cart-percent-with-custom-attribute#request-example)The second argument is the custom attribute type, with one of the following values:`string``boolean``integer``float`The third argument is the values of the expected type based on the second argument. For example, based on the `member_status` and custom attribute type, the values could be `gold`, `silver`, and `platinum`.Note that the maximum number of objects in the `args` array is 24. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
     "data": {
        "type": "rule_promotion",
        "name": "50 percent off cart with custom attribute",
        "description": "50 percent off cart with custom attribute",
        "enabled": true,
        "automatic": true,
        "start": "2024-01-01",
        "end": "2024-01-26",
        "rule_set": {
            "rules": {
                "strategy": "cart_custom_attribute",
                "operator": "in",
                "args": [
                    "member_status",
                    "string",
                    "gold",
                    "platinum"
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        50
                    ]
                }
            ]
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "e42ec2df-5682-4047-bc22-9e5eb932ca4a",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "50 percent off cart with custom attribute",
        "description": "50 percent off cart with custom attribute",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "catalog_ids": null,
            "currencies": null,
            "rules": {
                "strategy": "cart_custom_attribute",
                "operator": "in",
                "args": [
                    "member_status",
                    "string",
                    "gold",
                    "platinum"
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        50
                    ]
                }
            ]
        },
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-26T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-01-24T21:27:13.1Z",
                "updated_at": "2024-01-24T21:27:13.1Z"
            }
        }
    }
}
```

---

## Create a Mix of Cart and Item Percent Discount

## `POST` Create a Mix of Cart and Item Percent Discount

You can create a rule promotion using a combination of cart and item percent discount.

For example, you can create a mixed promotion strategy involving both cart and item percent discounts, where eligible shoppers receive a 20% discount on the entire cart and a 50% discount on specific items, such as `sku1`.

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions of the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "Buy sku1 and get cart 20% off and item sku1 50%",
        "description": "Buy sku1 and get cart 20% off and item sku1 50%",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-01",
        "end": "2024-02-10",
        "rule_set": {
            "rules": {
                "strategy": "and",
                "children": [
                    {
                        "strategy": "item_sku",
                        "operator": "in",
                        "args": [
                            "sku1"
                        ]
                    }
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        50
                    ],
                    "condition": {
                        "strategy": "and",
                        "children": [
                            {
                                "strategy": "item_sku",
                                "operator": "in",
                                "args": [
                                    "sku1"
                                ]
                            }
                        ]
                    }
                },
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        20
                    ]
                }
            ]
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "57e20480-7a0c-49f1-88e7-34925dadceb9",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "Buy sku1 and get cart 20% off and item sku1 50%",
        "description": "Buy sku1 and get cart 20% off and item sku1 50%",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "rules": {
                "strategy": "item_sku",
                "operator": "in",
                "args": [
                    "sku1"
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        50
                    ],
                    "condition": {
                        "strategy": "and",
                        "operator": "",
                        "args": null,
                        "children": [
                            {
                                "strategy": "item_sku",
                                "operator": "in",
                                "args": [
                                    "sku1"
                                ]
                            }
                        ]
                    }
                },
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        20
                    ]
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-03-13T15:35:15.641Z",
                "updated_at": "2024-03-13T15:35:15.641Z"
            }
        }
    }
}
```

---

## Create an Item Percent Discount with Product Attribute

## `POST` Create an Item Percent with Product Attribute

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```
To learn how to create product attributes, see [Product Attributes](/docs/api/flows/create-a-field).

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
     "data": {
        "type": "rule_promotion",
        "name": "Items with item attribute discount",
        "description": "All items with attribute brand EP get 20% discount",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-01",
        "end": "2050-01-01",
        "rule_set": {
          "rules": {
            "strategy": "item_attribute",
            "operator": "in",
            "args": [
              "products(product_template)",
              "brand",
              "string",
              "EP"
        ]
      },
          "actions": [
        {
            "strategy": "item_discount",
            "args": [
            "percent",
            20
          ]
        }
      ]
    }
  }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "57c02731-54ef-42f3-86d0-aaae0ef03610",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "Items with item attribute discount",
        "description": "All items with attribute brand EP get 20% discount",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "rules": {
                "strategy": "item_attribute",
                "operator": "in",
                "args": [
                    "products(product_template)",
                    "brand",
                    "string",
                    "EP"
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        20
                    ]
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-03-15T20:18:59.748Z",
                "updated_at": "2024-03-15T20:18:59.748Z"
            }
        }
    }
}
```

---

## Create an Item Fixed Discount

## `POST` Create an Item Fixed Discount

:::note
You can create an item discount where the minimum discount amount is either $0 or 0%.
:::

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "Buy item get $10 off",
        "description": "Buy item get $10 off",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-10",
        "end": "2024-02-22",
        "rule_set": {
            "rules": {
                "strategy": "and",
                "children": [
                    {
                        "strategy": "item_sku",
                        "operator": "in",
                        "args": [
                            "sku1"
                        ]
                    }
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "fixed",
                        10000
                    ]
                }
            ]
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "0c341523-6a7e-4195-8658-6dc3399d71e0",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "Buy item get $10 off",
        "description": "Buy item get $10 off",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "rules": {
                "strategy": "item_sku",
                "operator": "in",
                "args": [
                    "sku1"
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "fixed",
                        1000
                    ]
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-04-11T21:07:22.306Z",
                "updated_at": "2024-04-11T21:07:22.306Z"
            }
        }
    }
}
```

---

## Create an Item Fixed Price Discount

## `POST` Create an Item Fixed Price Discount

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "Buy 2 items for $100",
        "description": "Buy 2 items for $100",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-01",
        "end": "2050-01-01",
        "rule_set": {
            "rules": {
            "strategy": "item_sku",
            "operator": "in",
            "args": [
                "sku1"
            ]
        },
            "actions": [
            {
                "strategy": "item_discount",
                "args": [
                    "fixed_price",
                    2,
                    10000
                ]
            }
        ] 
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "488eba3d-fae1-4d9a-80e6-6baa2bf7fc83",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "Buy 2 items for $100",
        "description": "Buy 2 items for $100",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "rules": {
                "strategy": "item_sku",
                "operator": "in",
                "args": [
                    "sku1"
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "fixed_price",
                        2,
                        10000
                    ]
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-04-11T21:01:25.826Z",
                "updated_at": "2024-04-11T21:01:25.826Z"
            }
        }
    }
}
```

---

## Create an Item Promotion with Sub Conditions

## `POST` Create an Item Rule Promotion with Sub Conditions

Sub conditions in Rule Promotions refer to additional criteria or conditions that must be met for a particular promotion to be applied.

For promotions applied at the item level, sub conditions are supported for: 

- `item_category`: Applies the promotion based on item category.
- `item_attributes`: Applies the promotion based on specific item attributes.
- `item_quantity`:  Applies the promotion based on the quantity of items.
- `item_sku`: Applies the promotion to specific SKUs.

When multiple sub conditions exist, they function as `and` conditions, requiring all sub conditions to be fulfilled for the promotion to be applied.

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

The following request example outlines how a 50% discount applies to items that meet all the specified conditions. The main rule is based on the cart's total value, while the sub conditions focus on item categories and attributes. 

Rules (`rule_set.rules.children`): Here, the sub-conditions specify the additional criteria for the promotion to apply:
 - `item_category`: Only items within a specified category are eligible.
 - `item_attribute`: Items must not have a specific attribute to qualify for the discount.

Actions (`rule_set.actions.condition`): Here, the sub conditions refines where the discount is applied, requiring further criteria:
 - `item_category`: The discount is applied only to items within a specified category.
 - `item_attribute`: Items with a specified attribute are excluded from the discount.

This promotion sets up a 50% discount that applies only to items that meet all of the following conditions:

- The total cart value is at least $100.
- The items are part of a specified category.
- The items do not possess a specific attribute (For example, "sale2024").

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "Items discount for a category excluding items with attribute",
        "description": "50% item discount excluding items with attribute when eligible items exceed $100",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-01",
        "end": "2050-01-01",
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    10000
                ],
                "children": [
                {
                    "strategy": "item_category",
                    "operator": "in",
                    "args": [
                        "{{categoryID}}"
                    ]
                },
                {
                    "strategy": "item_attribute",
                    "operator": "nin",
                    "args": [
                        "products(product_template)",
                        "sales",
                        "string",
                        "sale2024"
                        ]
                    }
                ]
            },
            "actions": [
            {
                "strategy": "item_discount",
                "args": [
                    "percent",
                    50
                ],
                "condition": {
                    "strategy": "item_category",
                    "operator": "in",
                    "args": [
                        "{{categoryID}}"
                    ],
                    "children": [
                    {
                        "strategy": "item_attribute",
                        "operator": "nin",
                        "args": [
                            "products(product_template)",
                            "sales",
                            "string",
                            "sale2024"
                            ]
                        }
                    ]
                }
            }
        ]
    }
 }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "f558aebb-5108-44dc-9022-a9d6422110cf",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "Items discount for a category excluding items with attribute",
        "description": "50% item discount excluding items with attribute when eligible items exceed $100",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    10000
                ],
                "children": [
                    {
                        "strategy": "item_category",
                        "operator": "in",
                        "args": [
                            "{{categoryID}}"
                        ]
                    },
                    {
                        "strategy": "item_attribute",
                        "operator": "nin",
                        "args": [
                            "products(product_template)",
                            "sales",
                            "string",
                            "sale2024"
                        ]
                    }
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        50
                    ],
                    "condition": {
                        "strategy": "item_category",
                        "operator": "in",
                        "args": [
                            "{{categoryID}}"
                        ],
                        "children": [
                            {
                                "strategy": "item_attribute",
                                "operator": "nin",
                                "args": [
                                    "products(product_template)",
                                    "sales",
                                    "string",
                                    "sale2024"
                                ]
                            }
                        ]
                    }
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-05-14T19:31:37.135Z",
                "updated_at": "2024-05-14T19:31:37.135Z"
            }
        }
    }
}
```

---

## Create an Item Discount with Condition

## `POST` Create an Item Discount with Condition

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "Buy X get Y 50%",
        "description": "Buy X get Y 50%",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-01",
        "end": "2024-02-27",
        "rule_set": {
            "rules": {
                "strategy": "item_sku",
                "operator": "in",
                "args": [
                    "sku1"
                    ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        50
                    ],
                    "condition": {
                        "strategy": "and",
                        "children": [
                            {
                                "strategy": "item_sku",
                                "operator": "in",
                                "args": [
                                    "sku2"
                                ]
                            }
                        ]
                    }
                }
            ]
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "2977c021-0f15-4674-914e-c19f868e179a",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "Buy X get Y 50%",
        "description": "Buy X get Y 50%",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "rules": {
                "strategy": "item_sku",
                "operator": "in",
                "args": [
                    "sku1"
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        50
                    ],
                    "condition": {
                        "strategy": "and",
                        "children": [
                            {
                                "strategy": "item_sku",
                                "operator": "in",
                                "args": [
                                    "sku2"
                                ]
                            }
                        ]
                    }
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-04-12T13:13:32.422Z",
                "updated_at": "2024-04-12T13:13:32.422Z"
            }
        }
    }
}
```

---

## Create an Item Percent Discount with Limitations and Conditions

## `POST` Create an Item Percent Discount with Limitations and Conditions

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data": {
        "type": "rule_promotion",
        "name": "Buy X get one Y for free",
        "description": "Buy X get ONLY one Y for free",
        "enabled": true,
        "automatic": true,
        "start": "2024-02-01",
        "end": "2050-01-01",
        "rule_set": {
          "rules": {
            "strategy": "item_sku",
            "operator": "in",
            "args": [
              "sku1"
          ]
        },
          "actions": [
        {
            "strategy": "item_discount",
            "args": [
              "percent",
              100
            ],
            "limitations": {
              "max_quantity": 1
          },
            "condition": {
              "strategy": "and",
                "children": [
              {
                  "strategy": "item_sku",
                  "operator": "in",
                  "args": [
                    "sku2"
                ]
              }
            ]
          }
        }
      ]
    }
  }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "c4294755-2b0b-4d22-9301-b97f6c3ea282",
        "store_id": "9cf58db9-f5bb-4507-b8f8-831c61e5de06",
        "name": "Buy X get one Y for free",
        "description": "Buy X get ONLY one Y for free",
        "enabled": true,
        "automatic": true,
        "rule_set": {
            "rules": {
                "strategy": "item_sku",
                "operator": "in",
                "args": [
                    "sku1"
                ]
            },
            "actions": [
                {
                    "strategy": "item_discount",
                    "args": [
                        "percent",
                        100
                    ],
                    "condition": {
                        "strategy": "and",
                        "children": [
                            {
                                "strategy": "item_sku",
                                "operator": "in",
                                "args": [
                                    "sku2"
                                ]
                            }
                        ]
                    },
                    "limitations": {
                        "max_quantity": 1
                    }
                }
            ]
        },
        "start": "2024-02-01T00:00:00Z",
        "end": "2050-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-04-12T13:14:18.994Z",
                "updated_at": "2024-04-12T13:14:18.994Z"
            }
        }
    }
}
```

---

## Promotions Builder API Overview

The Promotions Builder helps users create various types of promotions based on customizable conditions and actions. Through flexible rules and strategies, the Promotions Builder allows merchants to build complex promotions tailored to specific business needs.

## The Promotions Builder Object

| Name         | Type     | Required    | Description                             |
|:---------    |:---------|:------------|:----------------------------------------|
| `type`       | `string` |  Required   | Specifies the type of the resource. The type of resource for this promotion is `rule_promotion`. |
| `name`       | `string` |  Required   | Specifies a name for the promotion. |
| `description`| `string` |  Optional   | Specifies a description for the promotion. If not provided, you can update the description using the [Update](/docs/promotions-builder/promotions-builder-api/promotions-builder-management/update-a-promotion) endpoint. |
| `enabled`    |   `boolean`  | Required | Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`. |
| `automatic` |  `boolean` | Optional |  Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is `false`. When this value is set to `true`, a code is autogenerated. If this value is set to `false`, you must create the code manually. For more information about creating codes, see the [Create Promotion Codes](/docs/promotions-builder/promotions-builder-codes/create-promotion-codes) section.|
| `priority` | `integer` | Optional | Specifies the priority of the promotion. Priorities are represented as integers, with higher numbers indicating higher priority. Each priority value must be unique, so no two promotions can have the same priority number. If there is no priority set, the most recently created promotion will be applied. Expired or inactive promotions can have duplicate priorities, but they must be changed to unique when reactivated. To remove the priority, pass the `null` value in the [update a Promotion](/docs/promotions-builder/promotions-builder-api/promotions-builder-management/update-a-promotion). For example, see [Create a Promotion with Priority](/docs/promotions-builder/promotions-builder-api/cart-level-promotions/create-a-cart-fixed-discount#request-example---priority-and-stackable-flags). |
| `stackable` | `boolean` | Optional | Specifies whether multiple promotions can be stacked to the same cart. By default, it is set to `true`. If set to `false`, the promotions cannot be stacked with other promotions. To create a Promotion Builder, for example, see [Create a Promotion with Stackable Flag](/docs/promotions-builder/promotions-builder-api/cart-level-promotions/create-a-cart-fixed-discount#request-example---priority-and-stackable-flags). |
| `override_stacking` | `boolean` | Optional | Enables a promotion to be stacked with an otherwise **non-stackable** promotion. By default, it is set to `false`. When set to `true`, the promotion can stack with other promotions, including those that are usually **non-stackable**. When set to false, the promotion follows the default stackability rules and does not stack with non-stackable promotions. |
| `start`   |  `date` | Required | Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. For example, `"start": "2000-01-01 12:00"`. If no time is specified, the default start and end time is set to `00:00`. |
| `end`    | `date`  | Required  | Specifies the end date and time of the promotion or the end date of the promotion. |

## The `rule_set` Object

| Name         | Type     | Required    | Description                               |
|:---------    |:---------|:------------|:----------------------------------------|
| `rule_set.catalog_ids` | `string` | Optional | Specifies the catalogs that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when `rule_set.catalog_ids` is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion. |
| `rule_set.currencies` | `string` | Optional | Specifies currencies that are applied for the promotion. |
| `rule_set.rules.strategy` | `string` | Required | Specifies strategies for the rule. Strategy decides how the rules are applied. The following strategies provide different criteria for applying rules,  allowing for flexible and customizable promotion management:`account_tags`: Considers the tags of the account associated with the cart.`cart_total`: Considers the total value of items in the shopping cart.`cart_custom_attribute`: Represents custom attributes associated with the entire shopping cart.`item_price`: Indicates the price of individual items.`item_quantity`: Considers the quantity of individual items.`item_sku`: Pertains to specific item SKUs. Supports multiple SKUs separated by a comma. For example, [`sku1`,`sku2`].`item_category`: Relates to item categories. Supports multiple unique identifiers of categories separated by a comma. For example, [`cat1`,`cat2`].`item_attribute`: Involves item attributes, which include; Arguments: [`productTemplate`, `field slug value`, `field type`, `field value`]. For example, "Example: [`template-1`, `brand`, `string`, `Adidas`, `Nike`]". The maximum number of attribute values is 20.`item_product_id`: Displays the product ID. It can be used for items without SKU, like skuless bundles. See [Handling both Item SKU and Product ID together](/docs/promotions-builder/overview#handling-both-item-sku-and-product-id-together) When using these strategies, you can combine `and` or `or` as needed to specify the criteria. The  `and` strategy is applied when multiple conditions must all be met. The `or` strategy is applied when at least one of the multiple conditions must be met.|
| `rule_set.rules.children` | `string[array]` | Optional | Specifies an array of rules within a rule set, particularly used when multiple rules are involved in defining a promotion. This structure allows for incorporating several rules within the same `rule_set`, where each rule establishes the criteria necessary for discount eligibility.Additionally, you can include sub conditions within the `rule_set.rules.children`to add additional criteria or conditions that must be met for a particular promotion to be applied. This is helpful for configuring complex promotions that require multiple, layered criteria. For configuring promotions with sub conditions, See [Create a Cart Percent Discount with Sub Conditions](/docs/promotions-builder/promotions-builder-api/cart-level-promotions/create-a-cart-percent-discount-with-subconditions) and [Create an Item Promotion with Sub Condition](/docs/promotions-builder/promotions-builder-api/item-level-promotions/create-an-item-promotion-with-sub-conditions). |
| `rule_set.rules.operator` | `string` | Required | Specifies the operators used for the rule strategy. The `eq`, `gt`,`lt`,`gte`, and `lte` operators are supported in the following rule strategies:`cart_total``item_price``item_quantity`The `in` and `nin` operators are supported in the following rule strategies:`item_sku``item_category``cart_custom_attribute`The `contains_all` and `contains_any` operators are supported in the following rule strategies:`account_tags`The `range` operator takes two arguments, representing the minimum and maximum values of the range. Both values are inclusive. The `range` operator is supported in the following rule strategy:`cart_total` |
| `rule_set.rules.args` | `string` / `number` | Required | Represents the condition value associated with each rule within the rule set. The number of supported arguments varies based on the rule strategy:For `cart_total`, `item_price`, and `item_quantity` strategies, only one argument is supported.For `item_sku` and `item_category` strategies, the `args` field supports a minimum of 1 and a maximum of 400 arguments. See [Arguments](/docs/promotions-builder/overview#arguments) |

## The `actions` object

| Name         | Type     | Required    | Description                               |
|:-----------|:---------|:------------|:----------------------------------------|
|`rule_set.actions.strategy` | `string` | Required | Defines how the discount is applied. The available options are:`cart_discount``item_discount``shipping_discount``shipping_discount` applies to shipping groups and can use percentage, fixed discount, or fixed price discounts. See [Create a Shipping Discount](/docs/promotions-builder/promotions-builder-api/shipping-discount/create-a-shipping-discount). |
| `rule_set.actions.args` | `string`/`number` | Required | The first argument specifies the format for the discount value. The available options are:`fixed``percent``fixed_price`The second argument indicates the value associated with the first argument. For example, ["percent", 20]. In the case of `fixed_price`, the second argument indicates the multiplier, for example, X for amount, and the third argument is the price. For example, ["fixed_price", 4, 100]. See [Arguments](/docs/promotions-builder/overview#arguments)|
| `rule_set.actions.condition` | `object` | Optional | Defines how to apply discounts based on specified conditions. It supports multiple conditions and utilizes various strategies, operators, and arguments to determine when to apply the discount. See [Create a Promotion with Conditions](/docs/promotions-builder/promotions-builder-api/item-level-promotions/create-item-discount-with-condition). Additionally, you can also include sub condition under `actions` object. A sub condition is an additional condition that further refines or restricts when the action associated with the rule should be executed. It provides more granularity and specificity to the rule, ensuring that the action is applied only under certain circumstances. See [Create a Cart Percent Discount with Sub Conditions](/docs/promotions-builder/promotions-builder-api/cart-level-promotions/create-a-cart-percent-discount-with-subconditions) and [Create an Item Promotion with Sub Condition](/docs/promotions-builder/promotions-builder-api/item-level-promotions/create-an-item-promotion-with-sub-conditions)|
| `rule_set.actions.condition.strategy` | `string` | Required | Strategy specifies the condition strategy to be used. Available options include:`cart_total``item_price``item_quantity``item_sku``item_category`The `and` strategy is applied when multiple conditions must all be met. For `shipping_discount`, the only supported value is `shipping_type`. |
| `rule_set.actions.condition.operator` | `string` | Required | Supported operators depend on the strategy used. For example:`eq`, `gt`, `lt`, `gte`, and `lte` operators:Supported for `item_price` and `item_quantity``in` and `nin` operators: Supported for `item_sku`, `item_category`, and other strategies. For `shipping_discount`, only the `in` operator is supported. |
| `rule_set.actions.condition.args` | `string` | Required | Arguments for the condition are specified. This could be a single value or a list of values depending on the strategy and operator used. For example, for the `item_quantity` strategy with the `gte` operator, the argument `[4]` means that the condition is met if the quantity of the item is greater than or equal to 4.For `shipping_discount`, an array of shipping types can be specified, for example, ["FEDEX", "UPS"]. The maximum number of values is 400. |
| `rule_set.actions.limitations` | `object` | Optional | Defines how limitations are applied to promotions. These limitations dictate how the promotion can be used and what criteria must be met for it to be applied. For more information, see [Action Limitations](/docs/promotions-builder/promotions-builder-api/action-limitations/action-limitations-overview). |

## Sample Response

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "e42ec2df-5682-4047-bc22-9e5eb932ca4a",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "$5 off cart with custom attribute",
        "description": "$5 off cart with custom attribute",
        "enabled": true,
        "automatic": true,
        "priority": 100,
        "rule_set": {
            "catalog_ids": null,
            "currencies": null,
            "rules": {
                "strategy": "cart_custom_attribute",
                "operator": "in",
                "args": [
                    "member_status",
                    "string",
                    "gold",
                    "platinum"
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "fixed",
                        500
                    ]
                }
            ]
        },
        "stackable": true,
        "override_stacking": false,
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-26T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2024-01-24T21:27:13.1Z",
                "updated_at": "2024-01-24T21:27:13.1Z"
            }
        }
    }
}
```

---

## Delete a Promotion(Promotions-builder-management)

## `DELETE` Delete a Promotion

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID
```

## Parameters

### Path parameters

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl -X GET https://useast.api.elasticpath.com/v2/rule-promotions:promotionID \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

`204 No Content`

---

## Get a Promotion by ID

## `GET` Get a Promotion by ID

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID
```

## Parameters

### Path parameters

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl -X GET https://useast.api.elasticpath.com/v2/rule-promotions:promotionID \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "009527e4-1cb4-40c7-9da4-8cd2aed864cf",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "10% off cart rule",
        "description": "cart rule 10% off your order!",
        "enabled": false,
        "automatic": false,
        "rule": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    100
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "percent",
                        20
                    ]
                }
            ]
        },
        "start": "2024-01-01T00:00:00Z",
        "end": "2025-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2023-12-18T22:12:36.276Z",
                "updated_at": "2023-12-18T22:12:36.276Z"
            }
        }
    }
}
```

---

## Get Promotions

## `GET` Get all Promotions

```http
https://useast.api.elasticpath.com/v2/rule-promotions
```

## Parameters

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Query parameters

| Name     | Required | Type     | Description                          |
|:---------|:---------|:---------|:-------------------------------------|
| `filter` | Optional | `string` | Filter attributes. For more information, see [Filtering](#filtering). |

## Filtering

Promotion codes are case-insensitive. You can search for codes using only `numbers` or codes containing both `string` and `numbers`.

The following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](/guides/Getting-Started/filtering#supported-characters).

| Attribute | Type     | Operator    | Example        |
|:--------- |:---------|:------------|:---------------|
| `id`      | `string`, `number` |  `eq`,`in`,`gt`,`lt`,`le`,`ge`       |  `eq(id,00000000-0000-4000-0000-000000000000)` |
| `code`    | `string`, `number` |  `eq`       |  `eq(code,summer2024)` |
| `name`    | `string`           |  `like`,`ilike`       |  `ilike(name, Summer *)` |
| `enabled`    | `boolean`           |  `eq`       |  `eq(enabled, true)` |
| `stackable`    | `boolean`           |  `eq`       |  `eq(stackable, true)` |
| `override_stacking`    | `boolean`           |  `eq`       |  `eq(override_stacking, true)` |
| `start`      | `date` |  `lt`,`le`,`eq`,`gt`,`ge`       |  `lt(start,2025-01-01T00:00:00.000Z)` |
| `end`      | `date` |  `lt`,`le`,`eq`,`gt`,`ge`       |  `lt(end,2025-01-01T00:00:00.000Z)` |

## Request Example

```bash
curl -X GET https://useast.api.elasticpath.com/v2/rule-promotions \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "type": "rule_promotion",
            "id": "009527e4-1cb4-40c7-9da4-8cd2aed864cf",
            "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
            "name": "10% off cart rule",
            "description": "cart rule 10% off your order!",
            "enabled": false,
            "automatic": false,
            "rule": {
                "rules": {
                    "strategy": "cart_total",
                    "operator": "gte",
                    "args": [
                        100
                    ]
                },
                "actions": [
                    {
                        "strategy": "cart_discount",
                        "args": [
                            "percent",
                            20
                        ]
                    }
                ]
            },
            "start": "2024-01-01T00:00:00Z",
            "end": "2025-01-01T00:00:00Z",
            "meta": {
                "timestamps": {
                    "created_at": "2023-12-18T22:12:36.276Z",
                    "updated_at": "2023-12-18T22:12:36.276Z"
                }
            }
        },
…
}
```

---

## Update a Promotion(Promotions-builder-management)

## `PUT` Update a Promotion

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID
```

## Parameters

### Path parameters

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the promotion to be updated. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/rule-promotions:promotionID \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
     "data": {
        "type": "rule_promotion",
        "name": "$10 off cart rule - updated",
        "description": "updated cart rule $10 off your order!",
        "enabled": false,
        "automatic": false,
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "lt",
                "args": [
                    1000
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "fixed",
                        10
                    ]
                }
            ]
        },
        "start": "2024-01-01T00:00:00Z",
        "end": "2025-01-01T00:00:00Z"
    }
}
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "009527e4-1cb4-40c7-9da4-8cd2aed864cf",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "$10 off cart rule - updated",
        "description": "updated cart rule $10 off your order!",
        "enabled": false,
        "automatic": false,
        "rule": {
            "rules": {
                "strategy": "cart_total",
                "operator": "lt",
                "args": [
                    1000
                ]
            },
            "actions": [
                {
                    "strategy": "cart_discount",
                    "args": [
                        "fixed",
                        10
                    ]
                }
            ]
        },
        "start": "2024-01-01T00:00:00Z",
        "end": "2025-01-01T00:00:00Z",
        "meta": {
            "timestamps": {
                "created_at": "2023-12-18T22:12:36.276Z",
                "updated_at": "2023-12-18T22:12:36.276Z"
            }
        }
    }
}
```

You can pass the following request to update the Rule Promotion with the `priority` setting:

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/rule-promotions:promotionID \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
     "data": {
        "type": "rule_promotion",
        "priority": 90
         }
}
```
To remove the `priority` field, update `priority` to `null`:

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/rule-promotions:promotionID \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d {
       "data": {
         "type": "rule_promotion",
         "priority": null
       }
     }
```

---

## Create a Shipping Discount

## `POST` Create a Shipping Discount

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID
```
The shipping discount applies to the shipping group base price and does not apply to shipping taxes or additional fees. See [Create a cart shipping group](/docs/ship-groups/shipping-groups/shipping-groups-api/create-cart-shipping-group.mdx) for how to set the shipping prices.

## Parameters

### Path parameters

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Body

For descriptions about the fields, refer to [Promotions Builder API overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview).

## Request Example

In the request below, the discount is only applied to shipping groups with the "fedex_ground" `shipping_type`.

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/rule-promotions:promotionID \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
     "data": {
        "type": "rule_promotion",
        "name": "Free Fedex Ground shipping when cart is $100 or more",
        "description": "Free Fedex Ground shipping when cart is $100 or more",
        "enabled": true,
        "automatic": false,
        "start": "2024-08-01",
        "end": "2024-12-31",
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    10000
                ]
            },
            "actions": [
                {
                    "strategy": "shipping_discount",
                    "args": [
                        "percent",
                        100
                    ],
                    "condition":{
                        "strategy": "shipping_type",
                        "operator": "in",
                        "args": ["fedex_ground"]
                    }
                }
            ]
        }
    }
}
```

## Response Example

```json
{
    "data": {
        "type": "rule_promotion",
        "id": "fb22796d-eef6-4a89-af5f-8aab0f149011",
        "store_id": "85ea6cac-589a-4141-80d0-42b91aae73a7",
        "name": "Free Fedex Ground shipping when cart is $100 or more",
        "description": "Free Fedex Ground shipping when cart is $100 or more",
        "enabled": true,
        "automatic": false,
        "rule_set": {
            "rules": {
                "strategy": "cart_total",
                "operator": "gte",
                "args": [
                    10000
                ]
            },
            "actions": [
                {
                    "strategy": "shipping_discount",
                    "args": [
                        "percent",
                        100
                    ],
                    "condition": {
                        "strategy": "shipping_type",
                        "operator": "in",
                        "args": [
                            "fedex_ground"
                        ]
                    }
                }
            ]
        },
        "start": "2024-08-01T00:00:00Z",
        "end": "2024-12-31T00:00:00Z",
        "stackable": true,
        "meta": {
            "timestamps": {
                "created_at": "2024-08-22T17:33:41.406Z",
                "updated_at": "2024-08-22T17:33:41.406Z"
            }
        }
    }
}
```

---

## Anonymize Promotion Code Usages

## `Post` Anonymize Promotion Code Usages

```http
https://useast.api.elasticpath.com/v2/rule-promotions/usages/anonymize

```

Use this endpoint to anonymize promotion code usage. When anonymization is successful, Personal Identifiable Information such as the `customer_email` address is replaced with `*`.

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `usage_ids` | Required | `array [string]` | The unique identifiers of the usages to be anonymized. You can anonymize multiple usages at the same time. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/usages/anonymize \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $ {
      "data": {
        "usage_ids": ["333ad446-8611-435a-97e4-0d1aa970e6c7"]
  }
}
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "id": "333ad446-8611-435a-97e4-0d1aa970e6c7",
            "order_id": "b9b21932-a021-4b84-861f-501f1c222dfc",
            "code_id": "31b5877e-2c19-4d9c-9418-166d7759c8e7",
            "code": "unlimited",
            "times_used": 1,
            "used_on": "2024-08-15T23:27:18.068Z",
            "customer_id": "5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e",
            "customer_email": "**",
            "meta": {
                "timestamps": {
                    "updated_at": "2024-08-15T23:28:08.874Z"
                }
            },
            "updated_by": "Key-2439657140697170361",
            "anonymized": true
        }
    ]
}
```

---

## Create First time Shopper's Coupon Code

A first time shopper is a shopper who has not completed any purchases or authorized orders with the store. 

:::note
- Orders without payment transactions do not count as completed purchases. 
- Canceling or refunding an order does not reinstate first-time shopper status.
- A first-time shopper coupon code cannot have limited uses or be assigned to specific users, meaning the code cannot be restricted by the number of times it can be used or tied to a specific customer ID.
:::

## `POST` Create First-time Shopper's Coupon Code

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name           | Required | Type      | Description                          |
|:---------------|:---------|:----------|:-------------------------------------|
| `type`         | Required | `string`  | Specifies the type of the resource. The type of resource for promotions is `promotion_codes`. |
| `codes`        | Required | `array`   | Specifies the code details in an array of objects. |
| `codes[].code` | Required | `string`  | Specifies the string to use as a code for the promotion. |
| `is_for_new_shopper` | Optional | `boolean` | Indicates whether the coupon is for first-time shoppers. If set to `true`, the discount applies only if the shopper has never made a payment for an order in the store. If `false` or not provided, the discount applies to all shoppers. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "codes": [
          {
          "code": "first_time",
          "is_for_new_shopper": true
          }
        ]
      }
     }
```

## Response Example

`201 Created`

```json
{
    "data": [
        {
            "id": "7ba5cd3d-a6dc-4745-97e6-3957f8c050df",
            "code": "first_time",
            "is_for_new_shopper": true
        }
    ]
}
```

## Errors

For first time shoppers, the following error is returned when you attempt to create a code with `uses` or `user` parameters:

```json
{
    "errors": [
        {
            "status": 400,
            "source": "",
            "title": "Invalid Code",
            "detail": "Code - first_time_uses can't have limited uses or assigned to users since it's for first time shoppers."
        }
    ]
}
```

---

## Create Max Uses Per Shopper Promotion Codes

You can set number of uses allowed per shopper (including account user) for the promotion code. The limitation can also include guest shoppers. Guest shopper usages are being tracked by the cart with email. See [Cart with email API](/docs/api/carts/create-a-cart#contact-email)

## `POST` Create Max Uses Per Shopper Promotion Codes

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body
See [Promotion Codes object](/docs/promotions-builder/promotions-builder-codes/create-promotion-codes#body) for all other fields.

| Name           | Required | Type      | Description                          |
|:---------------|:---------|:----------|:-------------------------------------|
| `max_uses_per_shopper` | Optional | `object` | Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper. |
| `max_uses_per_shopper.max_uses` | Optional | `integer` | Sets max number of times the code can be used by a shopper. **NOTE:** This can not be set with `per_application` consume unit.|
| `max_uses_per_shopper.includes_guests` | Optional | `boolean` | The flag to include guest shoppers for the discount with max use restriction. **If this field is provided, the `max_uses` value is required.** If not provided, then the default will be false.When set to `true`: Guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code.The code can be used by registered shoppers.When set to `false`:Guest shoppers cannot use the promo code, even if the cart has an associated guest email.The code can be used by registered shoppers.|

## Set max uses limit for all shoppers (registered, guests and accounts)

The following example configures the promotion code to allow a maximum of one use per shopper, including guest shoppers with an email associated with their cart.

### Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "codes": [
          {
            "code": "one_per_shopper",
            "consume_unit": "per_checkout",
            "max_uses_per_shopper": {
                "includes_guests": true,
                "max_uses":1
            }
           }
        ]
    }
  }
```

### Response Example

`201 Created`

```json
{
    "data": [
        {
            "id": "8a1c73bc-7c15-41c3-a3ed-a0aa398c3984",
            "code": "one_per_shopper",
            "max_uses_per_shopper": {
                "max_uses": 1,
                "includes_guests": true
            },
            "consume_unit": "per_checkout"
        }
    ]
}
```
## Set max uses limit for the promotion code and max use per shoppers (registered, guests and accounts)

For example, the following promotion code configuration allows a total of 10 uses, with a maximum of 1 use per shopper. This means up to 10 different shoppers can use the code.

### Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "codes": [
          {
            "code": "one_time_use",
            "consume_unit": "per_checkout",
            "uses": 10,
            "max_uses_per_shopper": {
              "includes_guests": true,
              "max_uses": 1
            }
          }
        ]
      }
  }
```

### Response Example

`201 Created`

```json
{
    "data": [
        {
          "id": "0f977e65-30bb-485a-90de-0ad5f5455b7f",
          "code": "one_time_use",
          "uses": 10,
          "max_uses": 10,
          "max_uses_per_shopper": {
            "max_uses": 1,
            "includes_guests": true
          },
          "consume_unit": "per_checkout"
        }
    ]
}
```

## Set max uses limit for specific shopper

To limit the maximum usage for a specific shopper, there are two approaches.
In the examples below, the identified shopper can only use the promotion code once across all checkouts when the cart is checked out with the matching customer ID.

### Use `uses` and `user` with `customerID` value.

:::note
- Account user ID is currently not supported.
:::

### Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "codes": [
          {
            "code": "one_per_shopper",
            "consume_unit": "per_checkout",
            "uses": 1,
            "user": "{{customerID}}",
           }
        ]
    }
  }
```

### Response Example

`201 Created`

```json
{
    "data": [
        {
            "id": "8a1c73bc-7c15-41c3-a3ed-a0aa398c3984",
            "code": "one_per_shopper",
            "uses": 1,
            "max_uses": 1,
            "user": "5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e",
            "consume_unit": "per_checkout"
        }
    ]
}
```

### Use `user` with `customerID` value and `max_uses_per_shopper.max_uses`
### Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "codes": [
          {
            "code": "one_per_shopper",
            "consume_unit": "per_checkout",
            "user": "{{customerID}}",
            "max_uses_per_shopper": {
                "includes_guests": false,
                "max_uses":1
            }
           }
        ]
    }
  }
```

### Response Example

`201 Created`

```json
{
    "data": [
        {
            "id": "8a1c73bc-7c15-41c3-a3ed-a0aa398c3984",
            "code": "one_per_shopper",
            "user": "5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e",
            "max_uses_per_shopper": {
                "max_uses": 1,
                "includes_guests": false
            },
            "consume_unit": "per_checkout"
        }
    ]
}
```
When the shopper has consumed all the usages, and attempts to use the same promotion code again, the following cart response message will return.

```json
{
    "messages": [
      {
        "source": {
          "type": "promotion",
          "id": "38861a5c-81bb-43bc-8934-e30cde108579",
          "code": "one_per_shopper"
        },
        "title": "Fully Consumed",
        "description": "You've already fully consumed this promotion code"
      }
   ]
}
```

## Errors

When the request body includes `max_uses_per_shopper.includes_guests`, the `max_uses` field must also be provided with a value. Otherwise, an error will be returned.

```json
{
    "errors": [
        {
            "status": 400,
            "source": "data.codes.0.max_uses_per_shopper",
            "title": "missing_dependency",
            "detail": "Has a dependency on max_uses"
        }
    ]
}
```

When setting `max_uses_per_shopper.max_uses` with consume unit `per_application`, the following error will return.

```json
{
    "errors": [
        {
            "status": 422,
            "source": "",
            "title": "Unsupported consume unit",
            "detail": "Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features."
        }
    ]
}
```

---

## Create Promotion Codes(Promotions-builder-codes)

## `POST` Create Promotion Codes

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes
```

:::note
- The promotion codes are case-insensitive.
- Multiple promotions can have the same code name. This means that different promotions can be identified using the same code names, allowing shoppers to apply a single coupon code that triggers multiple promotions. For more information see [Duplicate Codes](#duplicate-codes).
:::

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name           | Required | Type      | Description                          |
|:---------------|:---------|:----------|:-------------------------------------|
| `type`         | Required | `string`  | Specifies the type of the resource. The type of resource for promotions is `promotion_codes`. |
| `codes`        | Required | `array`   | Specifies the code details in an array of objects. |
| `codes[].code` | Required | `string`  | Specifies the string to use as a code for the promotion. |
| `codes[].uses` | Optional | `integer` | Specifies the number of times the code can be used. If no value is set, the customer can use the code any number of times. |
| `codes[].user` | Optional | `string`  | Specifies the customer ID of the shopper who can use the code. For more information, see the [Create a customer](/docs/customer-management/customer-management-api/create-a-customer) section. |
| `consume_unit` | Optional | `string`  | Specifies whether the code is consumed per application or per checkout. The options are `per_application` or `per_checkout`. The default setting is `per_checkout`. With `per_checkout`,  the code is used once for each checkout, regardless of the number of items in the cart. When set to `per_application`, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point. |
| `is_for_new_shopper` | Optional | `boolean` | A flag indicating whether the coupon is for first-time shoppers. If set to `true`, the discount will only apply if the shopper has never made a payment on any order in the store. If set to `false` or left unset, it will be a regular discount that applies to all shoppers. When this flag is set to true, the coupon cannot have usage limitations or be assigned to specific users. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "codes": [
          {
          "code": "spring2024"
          },
          {
          "code": "summer2024",
          "consume_unit": "per_checkout"
          },
          {
          "code": "summer2024_limited",
          "consume_unit": "per_application",
          "uses": 5
          },
          {
          "code": "summer2024_memberOnly",
          "consume_unit": "per_application",
          "uses": 1,
          "user": "vip_shopper@email.com"
        }
    
      ]
    }
  }
```

## Response Example

`201 Created`

```json
{
    "data": [
        {
            "id": "0a985bab-8f20-4124-b832-2d39053dfc56",
            "code": "spring2024"
        },
        {
            "id": "519be2f4-1a8a-4d97-a292-f45e9f55e0dd",
            "code": "summer2024",
            "consume_unit": "per_checkout"
        },
        {
            "id": "bdf30707-d6f1-4914-9a17-bc1d45e62216",
            "code": "summer2024_limited",
            "uses": 5,
            "max_uses": 5,
            "consume_unit": "per_application"
        },
        {
            "id": "95981144-dbde-4b1e-af7f-b6268af2925d",
            "code": "summer2024_memberOnly",
            "user": "vip_shopper@email.com",
            "uses": 1,
            "max_uses": 1,
            "consume_unit": "per_application"
        }
    ]
}
```

## Duplicate Codes

Multiple promotions can have the same code name. This means that different promotions can be identified using the same code names, allowing shoppers to apply a single coupon code that triggers multiple promotions.

Duplicate promotion codes are allowed among promotions in the store, regardless of their enabled or disabled status and validity dates. However, duplicate codes cannot be created within the same promotion. Even when codes are duplicated, they can serve different purposes and have a different `consume_unit`. For example, one code may have `per_application` and limited use, while another code with the same name can have `per_checkout` and unlimited use.

When creating codes, a list of duplicated codes is returned:

```json
"messages": [
        {
            "source": {
                "type": "promotion_codes",
                "codes": [
                    "spring2024",
                    "summer2024"
                ]
            },
            "title": "Duplicate code names",
            "description": "Code names duplicated in other promotions"
        }
    ]
```

## Errors

You cannot create promotion codes for automatic promotions. The following error is returned if you attempt to do so:

```json
{
    "errors": [
        {
            "status": "422",
            "title": "No codes allowed",
            "detail": "Cannot add codes to automatic promotion"
        }
    ]
}
```

The following error is returned if you attempt to create a promotion code that already exists in the same rule promotion:

```json
{
    "errors": [
        {
            "status": "422",
            "title": "Duplicate code",
            "detail": "Promotion code already in use"
        }
    ]
}
```

---

## Delete a Single Promotion Code

## `DELETE` Delete a Single Promotion Code

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes/:code
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |
| `code` | Required | `string` | The code that you want to delete. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes/:code \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

`204 No Content`

---

## Delete Multiple Promotion Builder Codes

## `DELETE` Delete Multiple Promotion Builder Codes

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes/
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes/ \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ '{
      "data": {
        "type": "promotion_codes",
        "codes": [
          {
            "code": "spring2024"
          },
          {
            "code": "summer2024"
          },
          {
            "code": "summer2024_limited"
          },
          {
            "code": "fall2024_limited"
          },
          {
            "code": "winter_VIP_limited"
          }
      ]
    }'
```

## Response Example

`204 No Content`

---

## Get a Promotion Code Usage(Promotions-builder-codes)

## `GET` Get a Promotion Code Usage

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes/:code/usages
```

This endpoint retrieves the usage history of a specific promotion code within a specific promotion, including details like `order_id`, `code`, and `times_used`.

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier for the rule promotion. |
| `code` | Required | `string` | Specifies the name of the code. For example, `10OFF`.  |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Query parameters

| Name | Required | Type     | Description                      |
| ---- | -------- | -------- | -------------------------------- |
| `filter` | Optional | `string` | Filter attributes. For more information, see [Filtering](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages#filtering). |
| `page[limit]`  | Optional | `integer` | The number of records per page. |
| `page[offset]` | Optional | `integer` | The number of records to offset the results by. |
| `sort` | Optional | `string` | Supported attribute is `used_on`. When specified, the results are sorted in an ascending order. To sort in descending order, prefix the attribute with -, for example, `-used_on`. See [Sorting](/guides/Getting-Started/sorting). |

## Filtering 

The following operators and attributes are available for filtering usages:

| Attribute | Type | Operators | Example  |
| ---------| --------- | ---------------------------| -------- |
| `id` | `string` | `eq` | `eq(id,8dac76b3-9282-4730-b1dd-bdd2a95610cb)` |
| `code` | `string` | `eq` | `eq(code,cart1off)` | 
| `used_on` | `string` | `gt`,`ge`,`le` and `lt` | `gt(used_on,2023-07-11)` |

## Request Example

```bash
curl https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes/:code/usages \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

When a cart with a promotion is checked out using an `accountID`, the `accountID` will be included in the response.

`200 OK`

```json
{
    "data": [
        {
            "id": "96a80700-4895-4d74-b96f-3ea39417ed29",
            "order_id": "5728c924-cd08-4b4a-a36a-1a926ee92ad3",
            "code_id": "fd23fcc6-e2cc-4900-9505-d38147c3019a",
            "code": "bxgy",
            "times_used": 1,
            "used_on": "2024-08-15T18:25:41.209Z",
            "customer_email": "andy@example.com",
            "meta": {
                "timestamps": {
                    "updated_at": "2024-08-15T18:25:41.209Z"
                }
            },
            "anonymized": false,
            "account_id": "c40ee30c-f5f9-4a40-8f3f-08f7c652b0c5"
        }
    ],
    "links": {
        "current": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
        "first": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
        "last": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
        "prev": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
        "next": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10"
    },
    "meta": {
        "page": {
            "limit": 10,
            "offset": 0,
            "current": 1,
            "total": 1
        },
        "results": {
            "total": 1
        }
    }
}
```

---

## Get Promotion Builder Codes

## `GET` Get Promotion Codes

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "id": "2282a20a-448c-4f5b-aa61-e5070355e941",
            "code": "spring2024",
            "meta": {
                "timestamps": {
                    "created_at": "2024-03-15T19:00:12.813Z"
                }
            }
        },
        {
            "id": "af3c06c1-8b5a-4a78-99a9-7a906a05897d",
            "code": "summer2024",
            "uses": 1,
            "max_uses": 1,
            "consume_unit": "per_checkout",
            "meta": {
                "timestamps": {
                    "created_at": "2024-03-20T18:58:28.738Z"
                }
            }
        }
    ],
    "links": {
        "current": "https://useast.api.elasticpath.com/v2/rule-promotions/bbd7f4c6-4766-49de-b05b-14c6a644f8f7/codes?page[offset]=0&page[limit]=10",
        "first": "https://useast.api.elasticpath.com/v2/rule-promotions/bbd7f4c6-4766-49de-b05b-14c6a644f8f7/codes?page[offset]=0&page[limit]=10",
        "last": "https://useast.api.elasticpath.com/v2/rule-promotions/bbd7f4c6-4766-49de-b05b-14c6a644f8f7/codes?page[offset]=0&page[limit]=10",
        "prev": "https://useast.api.elasticpath.com/v2/rule-promotions/bbd7f4c6-4766-49de-b05b-14c6a644f8f7/codes?page[offset]=0&page[limit]=10",
        "next": "https://useast.api.elasticpath.com/v2/rule-promotions/bbd7f4c6-4766-49de-b05b-14c6a644f8f7/codes?page[offset]=0&page[limit]=10"
    },
    "meta": {
        "page": {
            "limit": 10,
            "offset": 0,
            "current": 1,
            "total": 1
        },
        "results": {
            "total": 2
        }
    }
}
```

---

## Get Promotion Usages

## `GET` Get Promotion Usages

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/usages
```

This endpoint retrieves the usage history of a specific promotion, including details such as `order_id`, `code`, and `times_used`.

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier for the rule promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Query parameters

| Name | Required | Type     | Description                      |
| ---- | -------- | -------- | -------------------------------- |
| `filter` | Optional | `string` | Filter attributes. For more information, see [Filtering](/docs/promotions-builder/promotions-builder-codes/get-promotion-usages#filtering). |
| `page[limit]`  | Optional | `integer` | The number of records per page. |
| `page[offset]` | Optional | `integer` | The number of records to offset the results by. |
| `sort` | Optional | `string` | Supported attribute is `used_on`. When specified, the results are sorted in an ascending order. To sort in descending order, prefix the attribute with -, for example, `-used_on`. See [Sorting](/guides/Getting-Started/sorting). |

## Filtering 

The following operators and attributes are available for filtering usages:

| Attribute | Type | Operators | Example  |
| ---------| --------- | ---------------------------| -------- |
| `id` | `string` | `eq` | `eq(id,8dac76b3-9282-4730-b1dd-bdd2a95610cb)` |
| `code` | `string` | `eq` | `eq(code,cart1off)` | 
| `used_on` | `string` | `gt`,`ge`,`le` and `lt` | `gt(used_on,2023-07-11)` |

## Request Example

```bash
curl https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/usages \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

When a cart with a promotion is checked out using an `accountID`, the `accountID` will be included in the response.

`200 OK`

```json
{
    "data": [
        {
            "id": "96a80700-4895-4d74-b96f-3ea39417ed29",
            "order_id": "5728c924-cd08-4b4a-a36a-1a926ee92ad3",
            "code_id": "fd23fcc6-e2cc-4900-9505-d38147c3019a",
            "code": "bxgy",
            "times_used": 1,
            "used_on": "2024-08-15T18:25:41.209Z",
            "customer_email": "andy@example.com",
            "meta": {
                "timestamps": {
                    "updated_at": "2024-08-15T18:25:41.209Z"
                }
            },
            "anonymized": false,
            "account_id": "c40ee30c-f5f9-4a40-8f3f-08f7c652b0c5"
        }
    ],
    "links": {
        "current": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
        "first": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
        "last": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
        "prev": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10",
        "next": "https://useast.api.elasticpath.com/v2/rule-promotions/26067b82-a50c-462c-b3ed-1ca77aa13bd1/usages?page[offset]=0&page[limit]=10"
    },
    "meta": {
        "page": {
            "limit": 10,
            "offset": 0,
            "current": 1,
            "total": 1
        },
        "results": {
            "total": 1
        }
    }
}
```

---

## Bulk Create Promotion Builder Codes

Use Promotion Jobs to bulk generate promotion codes. See [Promotion Jobs](/docs/api/promotions/promotion-jobs) for the workflow.

## `POST` Bulk Create Promotion Codes

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name           | Required | Type      | Description                          |
|:---------------|:---------|:----------|:-------------------------------------|
| `type`         | Required | `string`  | Specifies the type of the resource. The type of resource for promotions is `promotion_job`. |
| `job_type`        | Required | `string`   | Specifies the job type. Possible values: code_generate, code_export. |
| `name` | Optional | `string`  | Represents the name of the job. The maximum allowed length is 50. |
| `parameters.number_of_codes` | Required | `integer` | Specifies the number of codes to be generated. It cannot be greater than the maximum number of codes per promotion, which defaults at 1000. |
| `parameters.max_uses_per_code` | Optional | `integer`  | Specifies the maximum number of usages of a code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times. |
| `parameters.consume_unit` | Optional | `string`  | Specifies whether the code is consumed per application or per checkout. The options are `per_application` or `per_checkout`. The default setting is `per_checkout`. With `per_checkout`,  the code is used once for each checkout, regardless of the number of items in the cart. When set to `per_application`, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point. |
| `parameters.code_prefix` | Optional | `string` | Indicates the prefix to include with the promotion code. For example, when the generated value is aa2b-3c4d and the prefix value is set as summer, the promotion code becomes summer-aa2b-3c4d. |
| `parameters.code_length` | Optional | `string` | Specifies the code length, which ranges from 8 to 16 characters. The default code length is eight characters, and a dash is added after every four characters in the code. For example, aa2b-3c4d. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "job_type": "code_generate",
        "name": "Demo bulk code generate",
        "parameters": {
            "number_of_codes": 100,
            "max_uses_per_code": 1,
            "consume_unit": "per_checkout",
            "code_prefix":"summer-",
            "code_length": 8
        }
    }
  }
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "promotion_job",
        "id": "9bc1391c-1b65-419e-940e-66ed86c07001",
        "rule_promotion_id": "8c150382-b258-4c88-a2d4-b9ea0be74a07",
        "job_type": "code_generate",
        "name": "Demo bulk code generate",
        "parameters": {
            "number_of_codes": 100,
            "max_uses_per_code": 1,
            "consume_unit": "per_checkout",
            "code_prefix":"summer-",
            "code_length": 8
        },
        "status": "pending",
        "meta": {
            "timestamps": {
                "created_at": "2024-12-03T23:31:35.962680423Z",
                "updated_at": "2024-12-03T23:31:35.962680423Z"
            }
        }
    }
}
```
## Errors

You cannot create more than one promotion job at the same time. If you attempt to do so, the following error will be returned:

```json
{
    "errors": [
        {
            "status": "400",
            "title": "Too many jobs",
            "detail": "Only 1 pending or processing job is allowed per promotion."
        }
    ]
}
```

---

## Cancel Promotion Builder Job

Cancels an asynchronous job whose status is pending or processing. See [Promotion Jobs](/docs/api/promotions/promotion-jobs) for the workflow.

## `POST` Cancel Promotion Builder Job

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs/:jobID/cancel
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |
| `jobID` | Required | `string` | The unique identifier of the rule promotion job. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body
Empty body.

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs/:jobID/cancel \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {}
  }
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "promotion_job",
        "id": "9bc1391c-1b65-419e-940e-66ed86c07001",
        "rule_promotion_id": "8c150382-b258-4c88-a2d4-b9ea0be74a07",
        "job_type": "code_generate",
        "name": "Demo bulk code generate",
        "parameters": {
            "number_of_codes": 100,
            "max_uses_per_code": 1,
            "consume_unit": "per_checkout",
            "code_prefix":"summer-",
            "code_length": 8
        },
        "status": "cancelling",
        "meta": {
            "timestamps": {
                "created_at": "2024-12-03T23:31:40.962680423Z",
                "updated_at": "2024-12-03T23:31:40.962680423Z"
            }
        }
    }
}
```

## Errors

You cannot cancel completed job. If you attempt to do so, the following error will be returned:

```json
{
    "errors": [
        {
            "status": "422",
            "title": "Unprocessable Entity",
            "detail": "Only pending or processing jobs can be cancelled"
        }
    ]
}
```

---

## Export Promotion Builder Codes

Use Promotion Jobs to export promotion codes. See [Promotion Jobs](/docs/api/promotions/promotion-jobs) for the workflow.

## `POST` Export Promotion Builder Codes

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name           | Required | Type      | Description                          |
|:---------------|:---------|:----------|:-------------------------------------|
| `type`         | Required | `string`  | Specifies the type of the resource. The type of resource for promotions is `promotion_job`. |
| `job_type`        | Required | `string`   | Specifies the job type. Possible values: code_generate, code_export. |
| `name` | Optional | `string`  | Represents the name of the job. The maximum allowed length is 50. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $ {
      "data":{
        "type": "promotion_codes",
        "job_type": "code_export",
        "name": "Demo export codes",
    }
  }
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "promotion_job",
        "id": "bd5708f6-d330-40a2-a6bd-b2e44bb3ce02",
        "rule_promotion_id": "dd85ee8b-fddd-4ae8-9a4d-eb9404ead7bd",
        "job_type": "code_export",
        "name": "Demo export codes",
        "status": "pending",
        "meta": {
            "timestamps": {
                "created_at": "2024-12-04T00:03:46.388696042Z",
                "updated_at": "2024-12-04T00:03:46.388696042Z"
            }
        }
    }
}
```

## Errors

You cannot create more than one promotion job at the same time. If you attempt to do so, the following error will be returned:

```json
{
    "errors": [
        {
            "status": "400",
            "title": "Too many jobs",
            "detail": "Only 1 pending or processing job is allowed per promotion."
        }
    ]
}
```

---

## Get Promotion Builder Jobs

## `GET` Promotion Builder Jobs

```http
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                      |
|:-----|:---------|:---------|:---------------------------------|
| `promotionID` | Required | `string` | The unique identifier of the rule promotion. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/jobs \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "type": "promotion_job",
            "id": "9bc1391c-1b65-419e-940e-66ed86c07001",
            "rule_promotion_id": "8c150382-b258-4c88-a2d4-b9ea0be74a07",
            "job_type": "code_generate",
            "name": "promo builder",
            "parameters": {
              "number_of_codes": 100,
              "max_uses_per_code": 1,
              "consume_unit": "per_checkout",
              "code_prefix":"summer-",
              "code_length": 8
            },
            "status": "completed",
            "meta": {
                "timestamps": {
                    "created_at": "2024-12-03T23:31:35.962Z",
                    "updated_at": "2024-12-03T23:32:12.609Z"
                }
            },
            "result": {
                "generated": 100
            }
        }
    ]
}
```

---

## Introduction

Shipping groups or split shipping refers to the separation of cart or order items into distinct shipping groups, with common shipping elements for corresponding items defined at this group level. This can include separate delivery addresses, tracking details, delivery methods, or shipping prices for different sets of items. Split shipping allows users to organize, update, and attach shipping concepts to eCommerce offerings according to their specific business requirements.

For example, consider the following scenario:

1. A shopper adds a gaming console, laptop, and headphones to the cart, and wants to deliver these items to different addresses.
1. Generate shipping groups for a cart. See [Create a cart shipping group](/docs/ship-groups/shipping-groups/shipping-groups-api/create-cart-shipping-group).
1. Associate the cart items with the corresponding shipping group IDs. This step is important because it is necessary to associate items with shipping groups to include shipping groups in the corresponding cart, order, and totals. 
1. [Checkout](/docs/api/carts/checkout) a cart. An unpaid order is created, and the checked out cart shipping groups are linked to the corresponding order. When you [Get an Order](/docs/api/carts/get-an-order), you can see that the shipping groups are linked to that order.

:::note
- You cannot split a bundle into multiple shipping groups. Therefore, if a bundle is included in an order, the entire bundle is associated to the same shipping group. 
- The shipping prices do not impact eligibility for item-level and cart-level promotions.
:::

The following are the characteristics of shipping groups:
- Shipping groups are designed to function independently of the items, therefore, providing flexibility in handling various business scenarios and workflows, and allowing both new and existing customers to utilize shipping group features according to their business requirements.
- With shipping groups, you can integrate third-party shipping services (external shipping engines) to generate details associated with item shipments. By integrating external shipping engines through shipping APIs, businesses can streamline their shipping processes according to their requirements.
- We offer tracking fields for shipping groups, which include reference fields for cross-service awareness, tracking, and delivery estimates. See [cart shipping group](/docs/ship-groups/shipping-groups/shipping-groups-api/create-cart-shipping-group).
- When using shipping groups, shoppers have the flexibility to add different addresses to each shipping group. This means that each shipping group within an order can have a unique shipping address. Without shipping groups, the entire order would be associated with a single address.
- Shipping groups provide the ability to add shipping prices to them. The shipping display price includes the base, tax, fees, and total. These are required to calculate [cart and order totals](/guides/How-To/Carts/calculate-totals).

---

## Create a Cart Shipping Group

## `POST` Create a Cart Shipping Group

```http
https://useast.api.elasticpath.com/v2/carts/:id/shipping-groups
```

Use this endpoint to create a cart shipping group. Once you have created a cart shipping group, assign the shipping group to the cart item by associating the cart item with the shipping group ID. This is important because it is necessary to associate items with shipping groups in order to include shipping groups in the corresponding cart, order, and totals.

Use any one of the following endpoints to associate the cart shipping group to the cart item:

- [Add custom items to cart](/docs/api/carts/manage-carts#add-custom-item-to-cart)
- [Update cart item](/docs/api/carts/update-a-cart-item)

:::note
- Ensure that the currency of the cart matches with the currency of the cart shipping group. For example, when creating the cart shipping group, the currency must be in USD if the cart currency is in USD.
- If multiple cart items have the same shipping group ID, the shipping price is only calculated once.
:::

## Parameters

### Path parameters

| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `id` | Required | `string` | The unique identifier of the cart to create a shipping group. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |
| `X-MOLTIN-CURRENCY` | Optional | `string` | Specifies the currency to be used other than the store's default currency when creating a cart shipping group and linking it to the desired cart items. |

### Body

| Name   | Required | Type     | Description |
|:-------|:---------|:---------|:------------|
| `type` | Required | `string` | Represents the type of object being returned. Must be set to `shipping_group`. |
| `shipping_type` | Optional | `string` | Represents the type of shipment. The maximum character allowed is 50. For example, UPS Ground, Canada Post Expedited. |
| `tracking_reference` | Optional | `string` | Specifies the tracking reference of the shipment. The maximum character allowed is 50. For example, ground_1234. |
| `shipping_price` | Optional | `object` | Includes `shipping_price.base`,`shipping_price.tax`, and `shipping_price.fees`. |
| `shipping_price.base` | Optional | `number` | Specifies the base price of the shipment. If not provided, it is zero. |
| `shipping_price.tax` | Optional | `number` | Specifies the tax price applied to the shipment. If not provided, it is zero. |
| `shipping_price.fees` | Optional | `number` | Specifies the shipping fees applied to the shipment. If not provided, it is zero. |
| `delivery_estimate` | Optional | `object` | Specifies the delivery estimate object. |
| `delivery_estimate.start` | Optional | `string` | Represents the start date of the delivery. |
| `delivery_estimate.end` | Optional | `string` | Represents the end date of the delivery. |
| `address` | Optional | `object` | Specifies the details of the shipping address. |
| `address.first_name` | Optional | `string` | Specifies first name of the shipping recipient. | 
| `address.last_name` | Optional | `string` | Specifies last name of the shipping recipient. |
| `address.company_name` | Optional | `string` | Specifies company name of the shipping recipient. |
| `address.line_1` | Optional | `string` | Indicates first line of the shipping address. |
| `address.line_2` | Optional | `string` | Indicates second line of the shipping address. |
| `address.postcode` | Optional | `string` | Represents postal code of the shipping address. |
| `address.county` | Optional | `string` | Specifies the county of the shipping address. |
| `address.country` | Optional | `string` | Specifies the country of the shipping address. |
| `address.region`	| Optional | `string` |	Specifies the state, province, or region of the shipping address. |
| `address.instructions` |	Optional |`string` | Specifies shipping instructions. |

## Request Example

```bash
curl -X POST https://useast.api.elasticpath.com/v2/carts/:id/shipping-groups
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $ {
     "data": {
       "type": "shipping_group",
       "shipping_type": "UPS Ground",
        "tracking_reference": "ground_1234",
        "shipping_price": {
            "base":500,
            "tax":100,
            "fees":100
        },
        "delivery_estimate": {
            "start": "2023-04-25T00:00:00.000+00:00",
            "end": "2023-04-29T00:00:00.000+00:00"
        },
        "address": {
            "first_name": "Ron",
            "last_name": "Swanson",
            "phone_number": "",
            "company_name": "Ron Swanson Enterprises",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "postcode": "92802",
            "county": "Orange",
            "country": "US",
            "region": "CA",
            "instructions": ""
        }
    }
}
```

## Response Example

`201 Created`

```json
{
    "data": {
        "type": "shipping_group",
        "id": "eb063818-939a-458f-97a4-2601c0c2b445",
        "relation": "cart",
        "order_id": "",
        "cart_id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba",
        "shipping_type": "UPS Ground",
        "tracking_reference": "ground_1234",
        "address": {
            "first_name": "Ron",
            "last_name": "Swanson",
            "company_name": "Ron Swanson Enterprises",
            "phone_number": "",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "postcode": "92802",
            "county": "Orange",
            "country": "US",
            "region": "CA",
            "instructions": ""
        },
        "delivery_estimate": {
            "start": "2023-04-25T00:00:00Z",
            "end": "2023-04-29T00:00:00Z"
        },
        "created_at": "2023-06-23T16:36:10.71799334Z",
        "updated_at": "2023-06-23T16:36:10.717994647Z",
        "relationships": {
            "cart": {
                "data": {
                    "type": "cart",
                    "id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba"
                }
            }
        },
        "meta": {
            "shipping_display_price": {
                "total": {
                    "amount": 700,
                    "currency": "USD",
                    "formatted": "$7.00"
                },
                "base": {
                    "amount": 500,
                    "currency": "USD",
                    "formatted": "$5.00"
                },
                "tax": {
                    "amount": 100,
                    "currency": "USD",
                    "formatted": "$1.00"
                },
                "fees": {
                    "amount": 100,
                    "currency": "USD",
                    "formatted": "$1.00"
                }
            }
        }
    }
}
```

## Errors

When the currency of the cart shipping group does not match the currency of the cart, the following error response is returned:

```json
{
    "errors": [
        {
            "status": 400,
            "source": "request",
            "title": "Cart Currency Mismatch",
            "detail": "This cart uses USD, cannot add shipping group with currency GBP"
        }
    ]
}
```

---

## Get a Cart Shipping Group by ID

## `GET` Get a Cart Shipping Group by ID

```http
https://useast.api.elasticpath.com/v2/carts/:cartID/shipping-groups/:shippingGroupID
```

## Parameters 

### Path parameters

| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `cartID` | Required | `string` | The unique identifier of the cart to retrieve a shipping group for a cart. |
| `shippingGroupID` | Required | `string` | The unique identifier of the shipping group related to a cart. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl -X GET https://useast.api.elasticpath.com/v2/carts/:cartID/shipping-groups/:shippingGroupID
    -H "Authorization: Bearer XXXX" \
    -H "content-type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "shipping_group",
        "id": "eb063818-939a-458f-97a4-2601c0c2b445",
        "relation": "cart",
        "order_id": "",
        "cart_id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba",
        "shipping_type": "UPS Ground",
        "tracking_reference": "ground_1234",
        "address": {
            "first_name": "Ron",
            "last_name": "Swanson",
            "company_name": "Ron Swanson Enterprises",
            "phone_number": "",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "postcode": "92802",
            "county": "Orange",
            "country": "US",
            "region": "CA",
            "instructions": ""
        },
        "delivery_estimate": {
            "start": "2023-04-25T00:00:00Z",
            "end": "2023-04-29T00:00:00Z"
        },
        "created_at": "2023-06-23T16:36:10.717Z",
        "updated_at": "2023-06-23T16:36:10.717Z",
        "relationships": {
            "cart": {
                "data": {
                    "type": "cart",
                    "id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba"
                }
            }
        },
        "meta": {
            "shipping_display_price": {
                "total": {
                    "amount": 700,
                    "currency": "USD",
                    "formatted": "$7.00"
                },
                "base": {
                    "amount": 500,
                    "currency": "USD",
                    "formatted": "$5.00"
                },
                "tax": {
                    "amount": 100,
                    "currency": "USD",
                    "formatted": "$1.00"
                },
                "fees": {
                    "amount": 100,
                    "currency": "USD",
                    "formatted": "$1.00"
                }
            }
        }
    }
}
```

## Errors

When the shipping group is part of another cart, checked out, or doesn't exist, an error response similar to the one below is returned:

```json
{
    "errors": [
        {
            "status": 404,
            "title": "Shipping groups not found",
            "detail": "Shipping groups not found for this cart. Please verify the shipping groups exists for this cart and are not already associated with orders.",
            "meta": {
                "cart_id": "123",
                "shipping_group_ids": [
                    "4658e5e5-bbf3-4da2-92ef-a832dfcfe677"
                ]
            }
        }
    ]
}
```

---

## Get Cart Shipping Groups

## `GET` Get Cart Shipping Groups

```http
https://useast.api.elasticpath.com/v2/carts/:id/shipping-groups
```

## Parameters 

### Path parameters

| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `id` | Required | `string` | The unique identifier of the cart to retrieve shipping groups for a cart. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl -X GET https://useast.api.elasticpath.com/v2/carts/:id/shipping-groups
    -H "Authorization: Bearer XXXX" \
    -H "content-type: application/json" \
```

## Response Example

`200 Ok`

```json
{
    "data": [
        {
            "type": "shipping_group",
            "id": "eb063818-939a-458f-97a4-2601c0c2b445",
            "relation": "cart",
            "order_id": "",
            "cart_id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba",
            "shipping_type": "UPS Ground",
            "tracking_reference": "ground_1234",
            "address": {
                "first_name": "Ron",
                "last_name": "Swanson",
                "company_name": "Ron Swanson Enterprises",
                "phone_number": "",
                "line_1": "1 Sunny Street",
                "line_2": "",
                "postcode": "92802",
                "county": "Orange",
                "country": "US",
                "region": "CA",
                "instructions": ""
            },
            "delivery_estimate": {
                "start": "2023-04-25T00:00:00Z",
                "end": "2023-04-29T00:00:00Z"
            },
            "created_at": "2023-06-23T16:36:10.717Z",
            "updated_at": "2023-06-23T16:36:10.717Z",
            "relationships": {
                "cart": {
                    "data": {
                        "type": "cart",
                        "id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba"
                    }
                }
            },
            "meta": {
                "shipping_display_price": {
                    "total": {
                        "amount": 700,
                        "currency": "USD",
                        "formatted": "$7.00"
                    },
                    "base": {
                        "amount": 500,
                        "currency": "USD",
                        "formatted": "$5.00"
                    },
                    "tax": {
                        "amount": 100,
                        "currency": "USD",
                        "formatted": "$1.00"
                    },
                    "fees": {
                        "amount": 100,
                        "currency": "USD",
                        "formatted": "$1.00"
                    }
                }
            }
        },
        {
            "type": "shipping_group",
            "id": "90d6ebd3-1aa6-44f8-b19a-91ddd4da306d",
            "relation": "cart",
            "order_id": "",
            "cart_id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba",
            "shipping_type": "UPS Ground",
            "tracking_reference": "ground_1234",
            "address": {
                "first_name": "Ron",
                "last_name": "Swanson",
                "company_name": "Ron Swanson Enterprises",
                "phone_number": "",
                "line_1": "1 Sunny Street",
                "line_2": "",
                "postcode": "92802",
                "county": "Orange",
                "country": "US",
                "region": "CA",
                "instructions": ""
            },
            "delivery_estimate": {
                "start": "2023-04-25T00:00:00Z",
                "end": "2023-04-29T00:00:00Z"
            },
            "created_at": "2023-06-26T13:36:51.267Z",
            "updated_at": "2023-06-26T13:36:51.267Z",
            "relationships": {
                "cart": {
                    "data": {
                        "type": "cart",
                        "id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba"
                    }
                }
            },
            "meta": {
                "shipping_display_price": {
                    "total": {
                        "amount": 700,
                        "currency": "USD",
                        "formatted": "$7.00"
                    },
                    "base": {
                        "amount": 500,
                        "currency": "USD",
                        "formatted": "$5.00"
                    },
                    "tax": {
                        "amount": 100,
                        "currency": "USD",
                        "formatted": "$1.00"
                    },
                    "fees": {
                        "amount": 100,
                        "currency": "USD",
                        "formatted": "$1.00"
                    }
                }
            }
        }
    ]
}
```

---

## Get Order Shipping Group by ID

## `GET` Get Order Shipping Group by ID

```http
https://useast.api.elasticpath.com/v2/orders/:orderID/shipping-groups/:shippingGroupID
```

Once the checkout process is completed, an order is created, and the shipping group is associated with the order. The `relation` field in the response body is changed to `order`, and the relevant `order_id` is added to the shipping groups, indicating that the shipping group has been checked out.

## Parameters 

### Path parameters

| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `orderID` | Required | `string` | The unique identifier of the order to retrieve all shipping groups for an order. |
| `shippingGroupID` | Required | `string` | The unique identifier of the shipping group for an order. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl -X GET https://useast.api.elasticpath.com/v2/orders/:orderID/shipping-groups/:shippingGroupID
    -H "Authorization: Bearer XXXX" \
    -H "content-type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "shipping_group",
        "id": "e6044587-937c-4926-9132-40c9f7c9b677",
        "relation": "order",
        "order_id": "c2301903-7b32-4eaa-981b-0ed078789926",
        "cart_id": "1234",
        "shipping_type": "UPS Ground",
        "tracking_reference": "ground_1234",
        "address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "company_name": "Ron Swanson Enterprises",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "city": "Vancouver",
            "postcode": "92802",
            "county": "Orange",
            "country": "US",
            "region": "WA"
        },
        "delivery_estimate": {
            "start": "2023-04-26T22:52:19Z",
            "end": "2023-04-27T22:52:19Z"
        },
        "created_at": "2023-07-10T22:57:11.333Z",
        "updated_at": "2023-07-10T22:57:35.458Z",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "c2301903-7b32-4eaa-981b-0ed078789926"
                }
            }
        },
        "meta": {
            "shipping_display_price": {
                "total": {
                    "amount": 160,
                    "currency": "USD",
                    "formatted": "$1.60"
                },
                "base": {
                    "amount": 100,
                    "currency": "USD",
                    "formatted": "$1.00"
                },
                "tax": {
                    "amount": 50,
                    "currency": "USD",
                    "formatted": "$0.50"
                },
                "fees": {
                    "amount": 10,
                    "currency": "USD",
                    "formatted": "$0.10"
                }
            },
            "total_display_price": {
                "with_tax": {
                    "amount": 360,
                    "currency": "USD",
                    "formatted": "$3.60"
                },
                "without_tax": {
                    "amount": 360,
                    "currency": "USD",
                    "formatted": "$3.60"
                },
                "tax": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "0"
                },
                "discount": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "0"
                },
                "balance_owing": {
                    "amount": 360,
                    "currency": "USD",
                    "formatted": "360"
                },
                "paid": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "0"
                },
                "authorized": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "0"
                },
                "without_discount": {
                    "amount": 360,
                    "currency": "USD",
                    "formatted": "360"
                },
                "shipping": {
                    "amount": 160,
                    "currency": "USD",
                    "formatted": "$1.60"
                }
            }
        }
    }
}
```

## `GET` Include Items for a Shipping Group

```http
https://useast.api.elasticpath.com/v2/orders/:orderID/shipping-groups/:shippingGroupID?include=items
```

## Parameters

### Path parameters

| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `cartID` | Required | `string` | The unique identifier of the cart to retrieve a shipping group for a cart. |
| `shippingGroupID` | Required | `string` | The unique identifier of the shipping group related to a cart. |

### Query parameters
| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `include` | Required | `string` | The cart items for a shipping group. |

## Request Example

```bash
curl -X GET https://useast.api.elasticpath.com/v2/orders/:orderID/shipping-groups/:shippingGroupID?include=items
    -H "Authorization: Bearer XXXX" \
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "shipping_group",
        "id": "e6044587-937c-4926-9132-40c9f7c9b677",
        "relation": "order",
        "order_id": "c2301903-7b32-4eaa-981b-0ed078789926",
        "cart_id": "1234",
        "shipping_type": "UPS Ground",
        "tracking_reference": "ground_1234",
        "address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "company_name": "Ron Swanson Enterprises",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "city": "Vancouver",
            "postcode": "92802",
            "county": "Orange",
            "country": "US",
            "region": "WA"
        },
        "delivery_estimate": {
            "start": "2023-04-26T22:52:19Z",
            "end": "2023-04-27T22:52:19Z"
        },
        "created_at": "2023-07-10T22:57:11.333Z",
        "updated_at": "2023-07-10T22:57:35.458Z",
        "relationships": {
            "order": {
                "data": {
                    "type": "order",
                    "id": "c2301903-7b32-4eaa-981b-0ed078789926"
                }
            }
        },
        "meta": {
            "shipping_display_price": {
                "total": {
                    "amount": 160,
                    "currency": "USD",
                    "formatted": "$1.60"
                },
                "base": {
                    "amount": 100,
                    "currency": "USD",
                    "formatted": "$1.00"
                },
                "tax": {
                    "amount": 50,
                    "currency": "USD",
                    "formatted": "$0.50"
                },
                "fees": {
                    "amount": 10,
                    "currency": "USD",
                    "formatted": "$0.10"
                }
            },
            "total_display_price": {
                "with_tax": {
                    "amount": 360,
                    "currency": "USD",
                    "formatted": "$3.60"
                },
                "without_tax": {
                    "amount": 360,
                    "currency": "USD",
                    "formatted": "$.60"
                },
                "tax": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "0"
                },
                "discount": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "0"
                },
                "balance_owing": {
                    "amount": 360,
                    "currency": "USD",
                    "formatted": "$3.60"
                },
                "paid": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "0"
                },
                "authorized": {
                    "amount": 0,
                    "currency": "USD",
                    "formatted": "0"
                },
                "without_discount": {
                    "amount": 360,
                    "currency": "USD",
                    "formatted": "$3.60"
                },
                "shipping": {
                    "amount": 160,
                    "currency": "USD",
                    "formatted": "$1.60"
                }
            }
        }
    },
    "included": {
        "items": [
            {
                "type": "order_item",
                "id": "14f96347-b93d-4b48-9c2a-dd01cf604a13",
                "quantity": 1,
                "product_id": "",
                "name": "My Custom Item 5",
                "sku": "SKU5",
                "unit_price": {
                    "amount": 200,
                    "currency": "USD",
                    "includes_tax": true
                },
                "value": {
                    "amount": 200,
                    "currency": "USD",
                    "includes_tax": true
                },
                "links": {},
                "meta": {
                    "display_price": {
                        "with_tax": {
                            "unit": {
                                "amount": 200,
                                "currency": "USD",
                                "formatted": "$2.00"
                            },
                            "value": {
                                "amount": 200,
                                "currency": "USD",
                                "formatted": "$2.00"
                            }
                        },
                        "without_tax": {
                            "unit": {
                                "amount": 200,
                                "currency": "USD",
                                "formatted": "$2.00"
                            },
                            "value": {
                                "amount": 200,
                                "currency": "USD",
                                "formatted": "$2.00"
                            }
                        },
                        "tax": {
                            "unit": {
                                "amount": 0,
                                "currency": "USD",
                                "formatted": "0"
                            },
                            "value": {
                                "amount": 0,
                                "currency": "USD",
                                "formatted": "0"
                            }
                        },
                        "discount": {
                            "unit": {
                                "amount": 0,
                                "currency": "USD",
                                "formatted": "0"
                            },
                            "value": {
                                "amount": 0,
                                "currency": "USD",
                                "formatted": "0"
                            }
                        },
                        "without_discount": {
                            "unit": {
                                "amount": 200,
                                "currency": "USD",
                                "formatted": "$2.00"
                            },
                            "value": {
                                "amount": 200,
                                "currency": "USD",
                                "formatted": "$2.00"
                            }
                        }
                    },
                    "timestamps": {
                        "created_at": "2023-07-10T22:57:35Z",
                        "updated_at": "2023-07-10T22:57:35Z"
                    }
                },
                "relationships": {
                    "cart_item": {
                        "data": {
                            "type": "cart_item",
                            "id": "081f217f-c6e1-47ae-9e56-3cf2e746662c"
                        }
                    }
                },
                "shipping_group_id": "e6044587-937c-4926-9132-40c9f7c9b677"
            }
        ]
    }
}
```

---

## Get Order Shipping Groups

## `GET` Get Order Shipping Groups

```http
https://useast.api.elasticpath.com/v2/orders/:id/shipping-groups
```

Once the checkout process is completed, an order is created, and the shipping group is associated with the order. The `relation` field in the response body is changed to `order`, and the relevant `order_id` is added to the shipping groups, indicating that the shipping group has been checked out.

## Parameters 

### Path parameters

| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `id` | Required | `string` | The unique identifier of the order to retrieve all shipping groups for an order. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

## Request Example

```bash
curl -X GET https://useast.api.elasticpath.com/v2/orders/:id/shipping-groups
    -H "Authorization: Bearer XXXX" \
    -H "content-type: application/json" \
```

## Response Example

`200 OK`

```json
{
    "data": [
        {
            "type": "shipping_group",
            "id": "65eaafee-0a77-40f5-81b0-42b825bf1f71",
            "relation": "order",
            "order_id": "9ba16dd0-ef51-4ad3-97bc-c76dfe666499",
            "cart_id": "c9a5a598-0136-4db8-aa27-acd5505caa4b",
            "shipping_type": "UPS Ground",
            "tracking_reference": "ground_1234",
            "address": {
                "first_name": "Andy",
                "last_name": "Dwyer",
                "company_name": "Ron Swanson Enterprises",
                "line_1": "1 Sunny Street",
                "line_2": "",
                "city": "Vancouver",
                "postcode": "92802",
                "county": "Orange",
                "country": "US",
                "region": "WA"
            },
            "delivery_estimate": {
                "start": "2023-04-26T22:52:19Z",
                "end": "2023-04-27T22:52:19Z"
            },
            "created_at": "2023-06-27T23:15:38.625Z",
            "updated_at": "2023-06-27T23:15:50.839Z",
            "relationships": {
                "order": {
                    "data": {
                        "type": "order",
                        "id": "9ba16dd0-ef51-4ad3-97bc-c76dfe666499"
                    }
                }
            },
            "meta": {
                "shipping_display_price": {
                    "total": {
                        "amount": 160,
                        "currency": "USD",
                        "formatted": "$1.60"
                    },
                    "base": {
                        "amount": 100,
                        "currency": "USD",
                        "formatted": "$1.00"
                    },
                    "tax": {
                        "amount": 50,
                        "currency": "USD",
                        "formatted": "$0.50"
                    },
                    "fees": {
                        "amount": 10,
                        "currency": "USD",
                        "formatted": "$0.10"
                    }
                }
            }
        }
    ]
}
```

---

## Update a Cart Shipping Group

## `PUT` Update a Cart Shipping Group

```http
https://useast.api.elasticpath.com/v2/carts/:cartID/shipping-groups/shippingGroupID
```

## Parameters 

### Path parameters

| Name | Required | Type     | Description                             |
|:-----|:---------|:---------|:----------------------------------------|
| `cartID` | Required | `string` | The unique identifier of the cart to retrieve a shipping group for a cart. |
| `shippingGroupID` | Required | `string` | The unique identifier of the shipping group related to a cart. |

### Headers

| Name            | Required | Type     | Description                          |
|:----------------|:---------|:---------|:-------------------------------------|
| `Authorization` | Required | `string` | The Bearer token required to get access to the API. |

### Body

| Name   | Required | Type     | Description |
|:-------|:---------|:---------|:------------|
| `type` | Required | `string` | Represents the type of object being returned. Must be set to `shipping_group`. |
| `shipping_type` | Optional | `string` | Represents the type of shipment. The maximum character allowed is 50. For example, UPS Ground, Canada Post Expedited. |
| `tracking_reference` | Optional | `string` | Specifies the tracking reference of the shipment. The maximum character allowed is 50. For example, ground_1234. |
| `shipping_price` | Optional | `object` | Includes `shipping_price.base`,`shipping_price.tax`, and `shipping_price.fees`. |
| `shipping_price.base` | Optional | `number` | Specifies the base price of the shipment. If not provided, it is zero. |
| `shipping_price.tax` | Optional | `number` | Specifies the tax price applied to the shipment. If not provided, it is zero. |
| `shipping_price.fees` | Optional | `number` | Specifies the shipping fees applied to the shipment. If not provided, it is zero. |
| `delivery_estimate` | Optional | `object` | Specifies the delivery estimate object. |
| `delivery_estimate.start` | Optional | `string` | Represents the start date of the delivery. |
| `delivery_estimate.end` | Optional | `string` | Represents the end date of the delivery. |
|  `address` | Optional | `object` | Specifies the details of the shipping address. |
| `address.first_name` | Optional | `string` | Specifies first name of the shipping recipient. | 
| `address.last_name` | Optional | `string` | Specifies last name of the shipping recipient. |
| `address.company_name` | Optional | `string` | Specifies company name of the shipping recipient. |
| `address.line_1` | Optional | `string` | Indicates first line of the shipping address. |
| `address.line_2` | Optional | `string` | Indicates second line of the shipping address. |
| `address.postcode` | Optional | `string` | Represents postal code of the shipping address. |
| `address.county` | Optional | `string` | Specifies the county of the shipping address. |
| `address.country` | Optional | `string` | Specifies the country of the shipping address. |
| `address.region`	| Optional | `string` |	Specifies the state, province, or region of the shipping address. |
| `address.instructions` | Optional |`string` | Specifies shipping instructions. |

## Request Example

```bash
curl -X PUT https://useast.api.elasticpath.com/v2/carts/:cartID/shipping-groups/shippingGroupID
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: application/json" \
    -d $ {
     "data": {
       "type": "shipping_group",
       "shipping_type": "shipping-type-updated",
        "tracking_reference": "tracking-reference-updated",
        "shipping_price": {
            "base":500,
            "tax":100,
            "fees":100
        },
        "delivery_estimate": {
            "start": "2023-04-25T00:00:00.000+00:00",
            "end": "2023-04-29T00:00:00.000+00:00"
        },
        "address": {
            "first_name": "Ron",
            "last_name": "Swanson",
            "phone_number": "",
            "company_name": "Ron Swanson Enterprises",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "postcode": "92802",
            "county": "Orange",
            "country": "US",
            "region": "CA",
            "instructions": ""
        }
    }
}
```

## Response Example

`200 OK`

```json
{
    "data": {
        "type": "shipping_group",
        "id": "eb063818-939a-458f-97a4-2601c0c2b445",
        "relation": "cart",
        "order_id": "",
        "cart_id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba",
        "shipping_type": "shipping-type-updated",
        "tracking_reference": "tracking-reference-updated",
        "address": {
            "first_name": "Andy",
            "last_name": "Dwyer",
            "company_name": "Ron Swanson Enterprises",
            "phone_number": "",
            "line_1": "1 Sunny Street",
            "line_2": "",
            "city": "Vancouver",
            "postcode": "92802",
            "county": "Orange",
            "country": "US",
            "region": "WA",
            "instructions": ""
        },
        "delivery_estimate": {
            "start": "2023-04-26T22:52:19Z",
            "end": "2023-04-27T22:52:19Z"
        },
        "created_at": "2023-06-23T16:36:10.717Z",
        "updated_at": "2023-06-26T15:44:14.620214165Z",
        "relationships": {
            "cart": {
                "data": {
                    "type": "cart",
                    "id": "2b5cb684-7fdf-4a50-9e6a-9e880f7150ba"
                }
            }
        },
        "meta": {
            "shipping_display_price": {
                "total": {
                    "amount": 700,
                    "currency": "USD",
                    "formatted": "$7.00"
                },
                "base": {
                    "amount": 500,
                    "currency": "USD",
                    "formatted": "$5.00"
                },
                "tax": {
                    "amount": 100,
                    "currency": "USD",
                    "formatted": "$1.00"
                },
                "fees": {
                    "amount": 100,
                    "currency": "USD",
                    "formatted": "$1.00"
                }
            }
        }
    }
}
```

---

## Observable Events

You can integrate Subscriptions with external systems like enterprise resource planning, fulfilment and other systems. For example, when a subscriber updates their address, the Customer Relationship Management system is updated with the change.

Events are actions that occur in Subscriptions, such as a subscriber changing their address or a subscription changing from active to inactive. You can create custom functions that perform additional processing outside of Subscriptions, and create integrations so that when an event occurs in your store, the custom function is run.

Events are processed concurrently. This means that events may not be delivered in the order they are created. For example, if a subscription is updated multiple times, the events may not be delivered in the same sequence they were updated. Events operate on an "at least once" delivery policy. We aim to deliver messages within 30 minutes or less. Ensure that you design your receiving code accordingly.

For more information about integrating Subscriptions, see [**Integration Types**](/docs/api/integrations/integrations-introduction#integration-types).

| Resource | Action | Observable Key | Availability |
| --- | --- | --- | --- |
| Product | CreatedUpdatedDeleted | `subscription-product.created``subscription-product.updated``subscription-product.deleted` | Store |
| Plan |  CreatedUpdatedDeleted | `subscription-plan.created``subscription-plan.updated``subscription-plan.deleted` | Store |
| Offering |  CreatedUpdatedDeleted | `subscription-offering.created``subscription-offering.updated``subscription-offering.deleted` | Store |
| Subscription | CreatedCreate-failedPausedCanceledPending-cancelPending-pauseResumedClosed | `subscription.created``subscription.create-failed``subscription.canceled``subscription.paused``subscription.pending_cancel``subscription.pending_pause``subscription.resumed``subscription.closed` | Store |
| Job | CreatedUpdatedDeleted | `subscription-job.created``subscription-job.updated``subscription-job.deleted` | Store |
| Invoices | CreatedDeleted | `subscription-invoice.created``subscription-offering.deleted` | Store |
| Schedule | CreatedUpdatedDeleted | `subscription-schedule.created``subscription-schedule.updated``subscription-schedule.deleted` | Store |
| Subscriber | CreatedUpdatedDeleted | `subscription-subscriber.created``subscription-subscriber.updated``subscription-subscriber.deleted` | Store |